ivue 1.1.20 → 1.1.21

package/docs/docs/components/usage/CounterComposablesIvueDestructuring.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { CustomMouse } from './classes/CustomMouse';
 
-import { ivue, iref, iuse } from '../../../../src/ivue';
+import { ivue, iref, iuse } from 'ivue';
 
 class Counter {
   count = iref(0);

package/docs/docs/components/usage/classes/CustomMouse.ts

@@ -1,11 +1,13 @@
 import { useMouse } from '@vueuse/core';
-import { iref, iuse,  type UseComposable } from 'ivue';
+import { iuse,  type UseComposable } from 'ivue';
 
 type UseMouse = UseComposable<typeof useMouse>
 
 export class CustomMouse {
+  
   x: UseMouse['x'];
   y: UseMouse['y'];
+
   constructor(public test: number) {
     ({ x: this.x, y: this.y } = iuse(useMouse()))
   }

package/docs/docs/components/usage/functions/useCustomMouse.ts

@@ -3,18 +3,23 @@ import { useMouse } from '@vueuse/core';
 
 export function useCustomMouse() {
   const { x, y } = useMouse();
+
   const _sum = ref(0);
 
   function sum() {
     _sum.value = x.value + y.value;
   }
 
-  const total2 = computed(() => {
-    return _sum; // Returning with .value
+  const _total = computed(() => {
+    // Returning without .value, not entirely correctly, but will still work in Vue template.
+    // This is to test the impressive IVue unwrapping capabilities of deeply nested and confusing Refs
+    return _sum;
   });
 
   const total = computed(() => {
-    return total2; // Returning with .value
+    // Returning without .value, not entirely correctly, but will still work in Vue template.
+    // This is to test the impressive IVue unwrapping capabilities of deeply nested and confusing Refs
+    return _total;
   });
 
   return {

package/docs/docs/index.md

@@ -2,43 +2,51 @@
 import Button from './components/Button.vue'
 
 </script>
-# Infinite Vue Documentation
+# <span style="font-family: 'Public Sans'; ">ivue ∞ Infinite Vue</span> Documentation
 
 
 ## About
 
-**Infinite Vue &ndash; ivue** is a class based composable architecture for Vue 3, that unlocks infinite scalability for Vue 3 based apps. It allows you to extend the regular Vue 3 in a simple and elegant way.
+**<span style="font-family: 'Public Sans'; font-size: 125%;">ivue ∞ Infinite Vue</span>** is a class based composable architecture for Vue 3, that unlocks infinite scalability for Vue 3 based apps. It allows you to extend the regular Vue 3 in a simple and elegant Object Oriented way.
 
 ## `ivue` is
 
 
-<div style="padding-left:20px;">
+<div style="padding-left:20px; font-size: 20px; line-height: 32px;">
 ∞&nbsp; Simple like Options API<br />
 ∞&nbsp; Flexible like Composition API<br />
 ∞&nbsp; Extensible like TypeScript Class API<br />
-∞&nbsp; Minimal, Opaque & Elegant <br />
-∞&nbsp; 100% TypeScript Support<br />
+∞&nbsp; Robust, Minimal, Opaque & Unobtrusive<br />
+∞&nbsp; 100% VSCode / Intellij IDE Autocomplete Intellisence<br />
 ∞&nbsp; 100% Vue 3 Compatible<br />
 ∞&nbsp; 100% Test Covered<br />
+∞&nbsp; 100% Type Safe<br />
 ∞&nbsp; Production Ready<br />
 ∞&nbsp; Just <code>1.1kb</code> gzipped!<br />
 </div>
 
 
 ## Features
-<div style="padding-left:20px;">
-&ndash; Extensible Classes using JavaScript / TypeScript native Class API<br />
-&ndash; Improves DX by elegantly dealing with `.value`<br />
-&ndash; Extensible Props Defaults<br />
-&ndash; Extensible Emits<br />
-&ndash; Extensible Slots<br />
-&ndash; Fully Extensible Components<br />
-&ndash; Can be used both as a Store and a ViewModel for Components<br />
-&ndash; Provides Full TypeScript Support<br />
-&ndash; Extends Vue 3 TypeScript Capability<br />
-&ndash; Zero dependencies except Vue 3<br />
+<div style="padding-left:20px; font-size: 18px;line-height: 28px; ">
+&mdash;&nbsp; Extensible Classes using JavaScript / TypeScript native Class API<br />
+&mdash;&nbsp; Can be used as a Global Store and a ViewModel for Components<br />
+&mdash;&nbsp; Enhances Extensibility of Props Defaults, Props, Slots<br />
+&mdash;&nbsp; Improves DX by elegantly dealing with <code>.value</code><br />
+&mdash;&nbsp; Allows for Fully Extensible Component Architecture<br />
+&mdash;&nbsp; Extends Vue 3 TypeScript Capability<br />
+&mdash;&nbsp; Zero dependencies except Vue 3<br />
 </div>
 
+
+
+## Philosophy
+<center>
+Perfection is achieved, not when there is nothing more to add, <br />
+but when there is nothing left to take away.  
+
+<div style="padding-top: 5px; color:#888; font-size: 90%;">― Antoine de Saint-Exupéry</div>
+</center>
+
 ## Next Step
 
 <Button href="/pages/getting-started.html" label="Geting Started" />  &nbsp; or &nbsp; <Button href="/pages/introduction.html" label="Read Introduction" />

package/docs/docs/pages/api.md

@@ -22,7 +22,7 @@ Core `ivue(className, ...args)` initializer is able to infer and validate the co
 
 `ivue()` initializer function returns an extended Vue 3 `reactive()` object in which getters and setters are internally converted to computeds and adds `.toRefs()` method to the created object. Computeds auto-unwrap themselves when they are accessed as a reactive object property, so the `.value` properties and computeds get flattened in the resulting object and do not require `.value` to be accessed.
 
-`ivue()` replicates native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype chain thus supporting classical inheritance.
+`ivue()` replicates native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype ancestors chain thus supporting classical inheritance.
 
 **Returns:** `<IVue<T>>` or `ivue` `reactive()` object of an `AnyClass` class with flattened (de-Refed) `Refs` and `ComputedRefs` as properties.
 

package/docs/docs/pages/how-it-works.md

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import CounterBasic from '../components/usage/CounterBasic.vue'
 </script>
+
 # How it works?
 
 ## What ivue is NOT?
@@ -8,30 +9,40 @@ import CounterBasic from '../components/usage/CounterBasic.vue'
 To understand how ivue works and how it does it, it is important to understand what it does not do.
 
 ::: info `ivue` is different from other class based libraries
-&mdash; &nbsp;`ivue` does NOT inherit from a base class<br />
-&mdash; &nbsp;`ivue` does NOT use decorators to achieve its objectives<br />
-&mdash; &nbsp;`ivue` does NOT alter Vue 3 underlying behavior, but rather relies on it<br />
-&mdash; &nbsp;`ivue` is NOT the same as class components (though you can build components with it)
+&mdash; &nbsp;`ivue` does NOT inherit from a base Class.<br />
+&mdash; &nbsp;`ivue` does NOT use Decorators to achieve its objectives.<br />
+&mdash; &nbsp;`ivue` does NOT alter Vue 3 underlying behavior, but rather relies on it.<br />
+&mdash; &nbsp;`ivue` is NOT the same as Class Components (though you can build components with it).<br />
+&mdash; &nbsp;`ivue` aims to be opaque, by giving the developer the Class API reactivity system.<br />
+&mdash; &nbsp;`ivue` omits custom implementations of IOC Container, Decorators & Mixins, etc. by design.<br />
+&mdash; &nbsp;`ivue` enforces a sane default standard of operation to contain the ever flexible Class API.<br />
+:::
+
+::: tip IVUE IMPLEMENTS MINIMAL API ARCHITECTURE
+Things like IOC Container, Decorators, Traits, Mixins, etc. were omitted by design to slim down the surface area and scope of `ivue` core purpose, which was JavaScript / TypeScript Class API based reactivity. Any Traits, Decorators & IOC Container can be built around it using third-party libraries or roll your own systems. You are more than welcome to contribute in this area!
 :::
 
 ## How it works?
+
 ```ts
 export function ivue<T extends AnyClass>(
   className: T,
   ...args: InferredArgs<T>
-): IVue<T> 
+): IVue<T>;
 ```
+
 The main `ivue()` initializer function uses TypeScript to be able to infer and validate the constrcutor argument types of `AnyClass` and passes those arguments to the constructor of `AnyClass`.
 
 `ivue` allows you to pass any number of arguments into the class `constructor(arg1, arg2, arg3, ...etc)`
 
 `ivue()` initializer function returns an extended Vue 3 `reactive()` object in which getters and setters are internally converted to computeds and adds `.toRefs()` method to the created object. Computeds auto-unwrap themselves when they are accessed as a reactive object property, so the `.value` properties and computeds get flattened in the resulting object and do not require `.value` to be accessed.
 
-`ivue` replicates native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype chain thus supporting classical inheritance.
+`ivue` replicates native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype ancestors chain thus supporting classical inheritance.
 
-`ivue` aims to be opaque and minimal, just doing the minimum to convert a class to a reactive object, leaving the rest to be implemented using Vue 3 Composition API inside an initializer function called `.init()` 
+`ivue` aims to be opaque and minimal, just doing the minimum to convert a class to a reactive object, leaving the rest to be implemented using Vue 3 Composition API inside an initializer function called `.init()`
 
 ## Usage Recommendation
+
 `ivue` recommends all class properties to be defined as `ref()` to be able to interoperate with `defineExpose()`, if you simply pass reactive props which are not Refs through `defineExpose()`, they will lose reactivity. `ref()` refs just like computed refs get flattened into the `reactive()` object, so there is no need to worry about using `.value`. The `ref()` refs are necessary just internally for Vue 3 to know which refs to keep reactive, and we just convert the types back to their normal types as if they have no reactivity at all, so `Ref<number>` is `number` in `ivue`, so rather than going in the direction of complexifying the types, we are going in the opposite direction towards simplification.
 
 `ivue` recommends all class functions, getters and setters to be defined in plain full function style (not arrow functions), this allows all `ivue` classes to be extensible at any point. By using plain standard functions, getters and setters allows for any getter, setter, function or property to be overriden by extending this class. Arrow functions break full extensibility of classes, so avoid using them inside of classes.
@@ -40,7 +51,9 @@ See: [More Guidelines](/pages/guidelines.html)
 
 ## Minimal API Surface Area
 
-`ivue()` initializer function is the main API<br />
+`ivue()` initializer function is the main core function to initialize the `ivue` reactive object<br />
+`iref()` ref initializer instantiates the Ref but Unwraps its type as the raw type of the Ref<br />
+`iuse()` function converts the type of composables to they Unwraped raw types<br />
 `.init()` method helps initialize the reactive state like `watch`, `onMount`, etc.<br />
 `.toRefs()` method allows to interoperate with Vue 3 Composables<br />
 Utility Types help to achieve the rest of `ivue` capabilities
@@ -52,11 +65,12 @@ Utility Types help to achieve the rest of `ivue` capabilities
 Or [See on GitHub](https://github.com/infinite-system/ivue/blob/main/src/ivue.ts)
 
 ## 100% Vue 3 Compatible
+
 `.toRefs()` allows the object to be converted to Vue 3 native composable structure with full `.value`s, so it can interoperate with native composables if needed. `.toRefs()` is also often used to get refs for `v-bind()` in css styles.
 
 ## 100% TypeScript Support
 
-`ivue` is on the cutting edge of TypeScript and owes its capabilities to the latest developments in TypeScript. 
+`ivue` is on the cutting edge of TypeScript and owes its capabilities to the latest developments in TypeScript.
 
 `ivue` provides a set of utility types to make working with `Vue 3` even easier and more scalable.
 
@@ -68,4 +82,4 @@ You can clone the project and run `yarn test` yourself and examine the tests.
 
 ## Zero Dependencies
 
-`ivue` has zero dependencies except Vue 3.
+`ivue` has zero dependencies except Vue 3.

package/docs/docs/pages/introduction.md

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import Button from '../components/Button.vue'
 </script>
-# What is Infinite Vue?
+# What is <span style="font-family: 'Public Sans'; ">ivue ∞ Infinite Vue</span>?
 
 ## The Problem
 
@@ -18,12 +18,13 @@ See: [VueJs.org &ndash; Reactivity Transform](https://vuejs.org/guide/extras/rea
 &ndash;&nbsp; Simple like Options API<br />
 &ndash;&nbsp; Flexible like Composition API<br />
 &ndash;&nbsp; Extensible like TypeScript Class API<br />
-&ndash;&nbsp; Feature Complete, yet Minimal, Opaque & Unobtrusive<br />
+&ndash;&nbsp; Robust, Minimal, Opaque & Unobtrusive<br />
 &ndash;&nbsp; 100% Vue 3 Compatible<br />
 &ndash;&nbsp; 100% Test Covered<br />
 &ndash;&nbsp; 100% Type Safe<br />
 &ndash;&nbsp; Production Ready<br />
 &ndash;&nbsp; Just <code>1.1kb</code> gzipped!<br />
+&ndash;&nbsp; 100% VSCode / Intellij IDE Auto-complete Intellisence<br />
 </div>
 
 `ivue` is a powerful tool because it fully aligns itself with JavaScript / TypeScript Class API.
@@ -52,7 +53,7 @@ While procedural programming has its strength, it also comes with its own weakne
 
 ## Infinite Vue Class Achitecture
 
-`ivue` replicates native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype chain thus supporting classical inheritance.
+`ivue` replicates native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype ancestors chain thus supporting classical inheritance.
 
 By using TypeScript we are able to infer the arguments of the main `ivue()` initializer function and pass the arguments to the constructor.
 

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.1.19",
+    "ivue": "^1.1.20",
     "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.1.20",
+  "version": "1.1.21",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { PropType, isReactive, ref } from 'vue';
+import { PropType, isReactive } from 'vue';
 
 import {
   ExtractPropDefaultTypes,
@@ -7,15 +7,16 @@ import {
   getAllClassProperties,
   isClass,
   ivue,
+  iref,
   propsWithDefaults,
 } from '../ivue';
 
 class Basic {
-  id = ref('id') as unknown as string;
+  id = iref('id');
 }
 
 class Bit {
-  _testProperty = ref('test-value') as unknown as string;
+  _testProperty = iref('test-value');
   /** Setter without a getter. */
   set testProperty(value: string) {
     this._testProperty = value;
@@ -23,15 +24,15 @@ class Bit {
 }
 
 class Item extends Bit {
-  _width = ref(5) as unknown as number;
-  unit = ref('px') as unknown as string;
+  _width = iref(5);
+  unit = iref('px');
   get width(): string {
     return this._width + this.unit;
   }
   set width(value: number) {
     this._width = value;
   }
-  _height = ref(5) as unknown as number;
+  _height = iref(5);
   get height(): string {
     return this._height + this.unit;
   }
@@ -41,29 +42,29 @@ class Item extends Bit {
 }
 
 class ProductItem extends Item {
-  _productType = ref('generic') as unknown as string;
+  _productType = iref('generic');
   get productType() {
     return this._productType;
   }
   set productType(value) {
     this._productType = value;
   }
-  _productFit = ref('perfect-fit') as unknown as string;
+  _productFit = iref('perfect-fit');
   get productFit() {
     return this._productFit;
   }
-  _productId = ref(0) as unknown as number;
+  _productId = iref(0);
   set productId(value: number) {
     this._productId = 0;
   }
-  _productFeel = ref('sleek') as unknown as string;
+  _productFeel = iref('sleek');
   public get productFeel() {
     return this._productFeel;
   }
 }
 
 class StoreItem extends ProductItem {
-  _productType = ref('store') as unknown as string;
+  _productType = iref('store');
   get productType() {
     const prefix = super.productFeel ?? '';
     return (prefix ? prefix + ':' : '') + this._productType;
@@ -74,9 +75,9 @@ class StoreItem extends ProductItem {
 }
 
 class RetailStoreItem extends StoreItem {
-  _productType = ref('retail') as unknown as string;
+  _productType = iref('retail');
   /** Do not overwrite productType getter here, on purpose. */
-  productHistory = ref([]);
+  productHistory = iref([]);
   get testProperty() {
     return this._testProperty;
   }
@@ -89,9 +90,9 @@ let computedCalls = 0;
 let notComputedCalls = 0;
 
 class Entity {
-  _key = ref(0) as unknown as number;
-  height = ref(0) as unknown as number;
-  width = ref(0) as unknown as number;
+  _key = iref(0);
+  height = iref(0);
+  width = iref(0);
   constructor(height: number, width = 5) {
     this.height = height;
     this.width = width;
@@ -240,23 +241,23 @@ describe('ivue', () => {
       expect(item.width).toBe('10px');
     });
 
-    it('parent getters from the prototype chain are working', () => {
+    it('parent getters from the prototype ancestors chain are working', () => {
       const item = ivue(RetailStoreItem);
 
       expect(item.productType).toBe('sleek:retail');
     });
 
-    it('parent setters from the prototype chain are working', () => {
+    it('parent setters from the prototype ancestors chain are working', () => {
       const item = ivue(RetailStoreItem);
 
       expect(item.productType).toBe('sleek:retail');
       /** SET VIA SETTER */
-      // @ts-expect-error ivue supports setting set and get separately in different levels of class prototype chain
+      // @ts-expect-error ivue supports setting set and get separately in different levels of class prototype ancestors chain
       item.productType = 'new-retail';
       expect(item.productType).toBe('sleek:new-retail');
     });
 
-    it('parent setters that are set at different levels in the prototype chain work together in harmony', () => {
+    it('parent setters that are set at different levels in the prototype ancestors chain work together in harmony', () => {
       const item = ivue(RetailStoreItem);
       /**
        * Setter for product feel is set on @see {StoreItem} class,
@@ -273,7 +274,7 @@ describe('ivue', () => {
 
       expect(item._testProperty).toBe('test-value');
       /** SET VIA SETTER */
-      // @ts-expect-error ivue supports setting set and get separately in different levels of class prototype chain
+      // @ts-expect-error ivue supports setting set and get separately in different levels of class prototype ancestors chain
       item.testProperty = 'new-test-value';
       expect(item._testProperty).toBe('new-test-value');
     });

package/src/ivue.ts

@@ -33,7 +33,7 @@ export type IVueRefs<T = any> = {
 };
 
 /**
- * Unwraps Refs Recursively, helps resolve fully the bare value types of any type T
+ * Unwraps Ref Recursively, helps resolve fully the bare value types of any type T
  * because sometimes the Refs are returned as they are with `.value` from computeds,
  * thus inferring nested ComputedRef<ComputedRef<ComputedRef<Ref>>> types, which
  * are difficult to fully resolve to bare values without this utility.
@@ -166,7 +166,7 @@ export type ValueOf<T extends Record<any, any>, K> = T[K];
 export const descriptorsMap = new Map();
 
 /**
- * Get descriptors of an entire class prototype chain as a Map.
+ * Get descriptors of an entire class prototype ancestors chain as a Map.
  * Completely emulates JavaScript class inheritance chain for getters and setters.
  *
  * @param className
@@ -201,7 +201,7 @@ export function getAllClassDescriptors(className: AnyClass): Descriptors {
         }
       }
     );
-    /** Walk up the prototype chain. */
+    /** Walk up the prototype ancestors chain. */
     prototype = Object.getPrototypeOf(prototype);
   }
 
@@ -283,7 +283,7 @@ export function ivue<T extends AnyClass>(
 export const propsMap: Map<object, Set<string> | any> = new Map();
 
 /**
- * Get properties of an entire class prototype chain as a Map.
+ * Get properties of an entire class prototype ancestors chain as a Map.
  */
 export function getAllClassProperties(obj: object): Set<string> {
   /* Retrieve props from cache */
@@ -312,28 +312,33 @@ export function getAllClassProperties(obj: object): Set<string> {
 }
 
 /**
- * `iref` is an unwrapped type alias for Vue ref() function.
- * `iref` does not alter the behavior of ref(), but simply
- * transforms the type to an unwrapped ref value.
- * @param val
- * @returns
+ * `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>}
  */
 export function iref<T>(val?: T): UnwrapRef<T> {
   return ref(val) as unknown as UnwrapRef<T>;
 }
 
 /**
- * `iuse` stands for composable.
- * Returns unwrapped composable type definition without the Refs.
+ * Two modes of operation: 
+ * 1. `iuse()` converts the types of a Composable / Ref to pure raw type definition.
+ * Returns for all properties of an object an unwrapped raw type definition, 
+ * unwraps direct Refs & ComputedRefs as well.
+ * 
+ * 2. If AnyClass is supplied into `iuse(AnyClass, ...args)` and that class's ...args,
+ * it returns a '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 wrapper class context.
  */
-
 export function iuse<T extends AnyClass | Object>(
   val?: T,
   ...args: InferredArgs<T>
-): T extends AnyClass ? IVue<T> : UnwrapComposableReturn<T> {
+): T extends AnyClass ? InstanceType<T> : UnwrapComposableReturn<T> {
   return isClass(val)
     ? ivue(
-        val as T extends AnyClass ? T : never,
+        val as T extends AnyClass ? T : any,
         ...(args as InferredArgs<T>)
       ).toRefs()
     : (val as unknown as UnwrapComposableReturn<T>);