feat: new async fun & docs & examples

Author: srav001

README.md

@@ -1,78 +1,98 @@
 # vue-subscription
 
-This is a TypeScript module for Vue.js, which provides a function `useSubscription` that returns an object with a shallow reactive value, a subscriber, and a few extra methods.
+This is a TypeScript module for Vue.js, which provides a function `useSubscription` that returns an object with a reactive value, a subscriber, and a few extra methods.
 
-The `useSubscription` function takes an initial value and returns an object with a reactive value property that is a shallowRef of the initial value passed in, and Subscriber functions can be added to a Set of subscribers to be executed when the value is changed.
+The `useSubscription` function takes an initial value and returns an object with a reactive value of the initial value passed in, and Subscriber functions can be added to a Set of subscribers to be executed when the value is changed.
 
-The module also includes methods to add, delete and trigger the subscribers as well as a method to mutate the value of the object. The `useSubscription` also returns an internal object named `$sub` with all the methods except readonly without the prefix `$`.
+The module also includes methods to add, delete and trigger the subscribers as well as a method to mutate the value if it is a more complex datatype(typeof object).
 
 ## Usage
 
 ```typescript
+const $mySubscription = useSubscription('hello'); // Type will be string
+
+// Get the current value
+console.log($mySubscription.$value); // 'hello'
+
 function mySubscriber(value: string) {
 	console.log(`The value is now: ${value}`);
 }
 
-function example() {
-	const $mySubscription = useSubscription('hello');
+// Add a subscriber
+$mySubscription.$addSub(mySubscriber);
+// Manually trigger the subscribers if needed(rarely)
+$mySubscription.$triggerSubs(); // 'The value is now: hello'
 
-	// Get the current value
-	console.log($mySubscription.value); // 'hello'
+// Set the value
+$mySubscription.$value = 'world';
 
-	// Add a subscriber
-	$mySubscription.$subscriber = mySubscriber;
+// Subscriber runs here -  'The value is now: world'
 
-	// Set the value
-	$mySubscription.value = 'world';
+// Remove a subscriber (can be used in Unmount, beforeRouteLeave etc)
+$mySubscription.$deleteSub(mySubscriber);
 
-	// Subscriber runs here -  'The value is now: world'
+// Use the readonly version of the value
+const myReadonlyValue = $mySubscription.$read;
+console.log(myReadonlyValue.value); // 'world'
+```
 
-	// Manually trigger the subscribers if needed(rarely)
-	$mySubscription.$triggerSubs(); // 'The value is now: world'
+Example when using complex objects which won't be tracked deeply by default. Unless the subscriber is used in templates, watch, watchEffect and template you don't need to add the deep flag.
 
-	// Remove a subscriber (can be used in Unmount, beforeRouteLeave etc)
-	$mySubscription.$deleteSub(mySubscriber);
+```typescript
+const $mySubscription = useSubscription(
+	{
+		user: {
+			name: 'John',
+			isActive: false
+		}
+	},
+	// You can pass `true` as the deep flag to make the subscription deeply reactive if used in templates
+	true
+);
+// Add a subscriber
+$mySubscription.$addSub(data => {
+	console.log(`The data is now: ${JSON.stringify(data)}`);
+});
+
+function myMutator(data: typeof $mySubscription.$value) {
+	data.user.isActive = true;
+	return data;
+}
+
+// Trigger the subscribers
+$mySubscription.$triggerSubs(); // 'The data is now: { user: { name: 'John', isActive: false }}'
 
-	// Use the readonly version of the value
-	const myReadonlyValue = $mySubscription.$ref;
-	console.log(myReadonlyValue.value); // { name: 'world', age: 30 }
+function tester() {
+	// Mutate the value (only works if the value is an object)
+	$mySubscription.$mutate(myMutator);
+	// Subscriber runs here -  'The data is now: { user: { name: 'John', isActive: true }}'
 }
+tester();
 ```
 
-Example when using complex objects which won't be tracked deeply by default
+You can also destructure the properties to have a seperate getter and setter.
 
 ```typescript
-function mySubscriber(data: object) {
-	console.log(`The data is now: ${data}`);
-}
+const { $get, $set, $read, $addSub } = useSubscription('hello');
 
-function myMutator(data: object) {
-	data.isActive = true;
-	return data;
-}
-
-function example() {
-	const $mySubscription = useSubscription({
-		user: {
-			name: Sravan,
-			isActive: false
-		}
-	});
+// Get the current value
+console.log($get()); // 'hello'
 
-	// Get the current value
-	console.log($mySubscription.value); // '{ user: { name: Sravan, isActive: false }}'
+function mySubscriber(value: string) {
+	console.log(`The value is now: ${value}`);
+}
 
-	// Add a subscriber
-	$mySubscription.$subscriber = mySubscriber;
+// Add a subscriber
+$addSub(mySubscriber);
 
-	// Trigger the subscribers
-	$mySubscription.$triggerSubs(); // 'The data is now: { user: { name: Sravan, isActive: false }}'
+// Set the value
+$set('world');
 
-	// Mutate the value (only works if the value is an object)
-	$mySubscription.$mutate(myMutator);
+// Subscriber runs here -  'The value is now: world'
 
-	// Subscriber runs here -  'The data is now: { user: { name: Sravan, isActive: true }}'
+$set(val => `Hello ${val}`);
+// Subscriber runs here -  'The value is now: Hello world'
 
-	console.log($mySubscription.value); // '{ user: { name: Sravan, isActive: true }}'
-}
+// Use the readonly version of the value
+console.log($read.value); // 'Hello world'
 ```

demo/App.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import ChildComp from './childComp.vue';
+import { useEventBus } from './composables/eventBus';
+
+const testValue = ref(0);
+const eventBus = useEventBus();
+eventBus.$on((value) => {
+	testValue.value = value;
+									//  ^?
+});
+</script>
+
+<template>
+	<div style="margin: 10rem">
+		<h1>{{ testValue }}</h1>
+
+		<hr style="margin-top: 5rem; margin-bottom: 5rem" />
+		<h1>{{ eventBus.$state.value }}</h1>
+		<ChildComp />
+	</div>
+</template>

demo/ChildComp.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { useEventBus } from './composables/eventBus';
+
+const eventBus = useEventBus();
+function incrementer() {
+	eventBus.$emit(eventBus.$state.value + 1);
+}
+</script>
+
+<template>
+	<button style="margin: 5rem; padding: 2rem; border-radius: 50%" @click="incrementer()">Increase Count</button>
+</template>

demo/composables/eventBus.ts

@@ -0,0 +1,12 @@
+import { useSubscription } from '../../src/subscription';
+
+const myEventBus = useSubscription(0);
+
+export function useEventBus() {
+	return {
+		$on: myEventBus.$addSub,
+		$off: myEventBus.$deleteSub,
+		$emit: myEventBus.$set,
+		$state: myEventBus.$read
+	};
+}

demo/main.ts

@@ -0,0 +1,6 @@
+import { createApp } from 'vue';
+import App from '../demo/App.vue';
+
+const app = createApp(App);
+
+app.mount('#app');

index.html

@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <link rel="icon" href="/favicon.ico">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Vite App</title>
-  </head>
-  <body>
-    <div id="app"></div>
-    <script type="module" src="/src/main.ts"></script>
-  </body>
+	<head>
+		<meta charset="UTF-8" />
+		<link rel="icon" href="/favicon.ico" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Vite App</title>
+	</head>
+	<body>
+		<div id="app"></div>
+		<script type="module" src="/demo/main.ts"></script>
+	</body>
 </html>

src/App.vue

@@ -5,10 +5,17 @@
  * @param {T} arg - The argument to pass to the function.
  * @returns A promise that resolves to the result of the function.
  */
+// eslint-disable-next-line @typescript-eslint/ban-types
 export async function dynamicallyExecuteFunction<T>(func: Function, arg: T) {
-  if (func.constructor.name === 'AsyncFunction') {
-    return func(arg);
-  }
-
-  return Promise.resolve(func(arg));
+	try {
+		const result = func(arg);
+		if (result instanceof Promise) {
+			return await result;
+		} else {
+			return result;
+		}
+	} catch (err) {
+		// eslint-disable-next-line no-console
+		console.error(err);
+	}
 }