@iankibetsh/vue-streamline 1.3.0 → 1.3.2

package/README.md

@@ -1,91 +1,437 @@
-# vue-streamline
+# Streamline Vue Plugin
 
-Vue library for streamlining laravel backend services with @iankibet/streamline composer package
+A robust Vue 3 plugin designed for seamless integration with Streamline backend services. It delivers reactive state management, intelligent caching, and dynamic action invocation.
 
 ## Installation
 
-```sh
+```bash
 npm install @iankibetsh/vue-streamline
 ```
 
-## Usage
+## Setup
 
-In your main.js file, import the library and register it as a plugin:
+### 1. Register the Plugin
 
-```js
-import {streamline} from '@iankibetsh/vue-streamline'
-```
+```javascript
+import { createApp } from 'vue';
+import { streamline } from '@iankibetsh/vue-streamline';
+import App from './App.vue';
+
+const app = createApp(App);
+
+// Define authentication headers
+const streamlineHeaders = {
+  Authorization: `Bearer ${localStorage.getItem('access_token')}`
+};
+
+// Construct the Streamline endpoint URL
+const streamlineUrl = `${import.meta.env.VITE_APP_API_URL}streamline`;
 
-```js
-Vue.use(streamline, {
-    streamlineHeaders: {
-        // Add any headers you want to send with the request
-    },
-    streamlineUrl: 'http://localhost:8000/api/streamline' // The url to the streamline route
-})
+app.use(streamline, {
+  streamlineHeaders,
+  streamlineUrl,
+  enableCache: true // Optional: enables local storage caching
+});
+
+app.mount('#app');
 ```
 
+### 2. Use in Components
+
+#### Option A: Full Streamline Integration
 
-## usage in vue component
+```vue
+<script setup>
+import { useStreamline } from '@iankibetsh/vue-streamline';
+
+const { service, loading, props, getActionUrl } = useStreamline('users', 1);
+</script>
+```
 
-```js
-import { useStreamline } from '@iankibet/vue-streamline'
+#### Option B: Standalone `getActionUrl`
 
+If you only need to generate action URLs without the full reactive service:
 
-const {getActionUrl, service:tasksService, props} = useStreamline('tasks')
+```vue
+<script setup>
+import { getActionUrl } from '@iankibetsh/vue-streamline';
 
+// Use directly in template or script
+const downloadUrl = getActionUrl('reports:download', reportId, 'pdf');
+</script>
+
+<template>
+  <a :href="getActionUrl('users:export', userId, 'csv')">Export User</a>
+  <h3>Action URL: {{ getActionUrl('users:listUsers', 'admin', 'active') }}</h3>
+</template>
 ```
 
-## Calling an action/method in the service
+## API Reference
+
+### `useStreamline(stream, ...initialArgs)`
+
+Primary composable for interfacing with Streamline services.
+
+#### Parameters
+
+- **`stream`** (`string`): Name of the target stream or service.
+- **`...initialArgs`** (`any`): Optional arguments passed to the stream’s `onMounted` action.
 
-You can call an action/method in the service by calling the method on the service object
-```js
-const res = await tasksService.getTasks()
+#### Returns
 
-// or
+An object with the following reactive properties and utilities:
 
-tasksService.getTasks().then(response => {
-    console.log(response)
-})
+| Property         | Type                  | Description |
+|------------------|-----------------------|-------------|
+| `service`        | Reactive Proxy        | Proxy for invoking stream actions dynamically. |
+| `loading`        | `ref<boolean>`        | Indicates ongoing operations. |
+| `props`          | Reactive Proxy        | Holds properties fetched from the stream. |
+| `getActionUrl`   | `Function`            | Generates URLs for specific actions. |
+| `confirmAction`  | `Function`            | Displays confirmation dialogs before actions. |
+
+---
+
+### `getActionUrl(action, ...args)`
+
+Standalone function for generating action URLs without reactive features.
+
+#### Parameters
+
+- **`action`** (`string`): Action name, optionally prefixed with stream name (e.g., `'stream:action'`).
+- **`...args`** (`any`): Arguments to pass as URL parameters.
+
+#### Returns
+
+- **`string`**: Fully qualified URL for the specified action.
+
+#### Usage
+
+```javascript
+import { getActionUrl } from '@iankibetsh/vue-streamline';
+
+// Simple action URL
+const url = getActionUrl('download', fileId);
+
+// Cross-stream action
+const analyticsUrl = getActionUrl('analytics:track', eventName, userId);
+
+// Multiple parameters
+const reportUrl = getActionUrl('reports:generate', reportId, 'pdf', '2024');
 ```
-A swal popup asking the user to confirm the action will be shown before the action is called
 
-## Pre Confirm Calling a action/method 
+---
+
+## Features
+
+### 1. Dynamic Action Calling
 
-You can pre confirm calling an action/method in the service by calling the method on the service object
-```js
-const res = await tasksService.confirm('Are you sure you want to delete this task?').deleteTask(1)
+Invoke backend actions via the `service` proxy:
+
+```javascript
+const { service, loading } = useStreamline('users');
+
+// Standard CRUD operations
+await service.fetchAll();
+await service.create({ name: 'John', email: 'john@example.com' });
+await service.update(1, { name: 'Jane' });
+await service.delete(5);
+
+// Custom actions with multiple arguments
+await service.customAction(arg1, arg2, arg3);
 ```
 
+### 2. Reactive Properties
 
-## Getting url to an action/method in the service
+Properties are fetched automatically upon component mount or first access:
 
-You can get the url to an action/method in the service by calling the getActionUrl method on the service object passing the action name and any parameters
-```js
-getActionUrl('getTasks', 'active')
- ```
+```javascript
+const { props, loading } = useStreamline('dashboard', userId);
 
-## Accessing class properties
-You can access the class properties defined in the service class using the props object returned by the useStreamline function
-### In your script
-Access the props object to get the class properties, use computed to make it reactive
-```js
-const title = computed(() => props.title)
+// Properties trigger fetch on access if not yet loaded
+console.log(props.statistics);
+console.log(props.userInfo);
+console.log(props.settings);
 ```
-Then use it in your template
-```html
+
+**Auto-fetch triggers:**
+- Component `onMounted` (when `initialArgs` are provided)
+- First property access on the `props` proxy
+
+### 3. Loading States
+
+Monitor operation status reactively:
+
+```vue
 <template>
-    <div>
-        <h1>{{title}}</h1>
+  <div>
+    <div v-if="loading">Loading...</div>
+    <div v-else>
+      <button @click="service.fetchData()">Fetch Data</button>
     </div>
+  </div>
+</template>
+
+<script setup>
+import { useStreamline } from '@iankibetsh/vue-streamline';
+
+const { service, loading } = useStreamline('data');
+</script>
+```
+
+### 4. Local Storage Caching
+
+Enable persistent caching across sessions:
+
+```javascript
+app.use(streamline, {
+  streamlineUrl: 'https://your-api.com/streamline',
+  enableCache: true
+});
+```
+
+**Behavior when enabled:**
+- Data is stored in `localStorage` using a unique key (stream + arguments).
+- Cached data loads instantly on mount.
+- Cache updates after successful fetch operations.
+- Keys are deterministic and scoped per stream and arguments.
+
+### 5. Manual Refresh
+
+Force reload of stream properties:
+
+```javascript
+const { service } = useStreamline('products', categoryId);
+
+// Refresh properties
+await service.refresh(); // or service.reload()
+```
+
+### 6. Confirmation Dialogs
+
+Prompt users before destructive actions:
+
+```javascript
+const { service } = useStreamline('users');
+
+// Default confirmation message
+await service.confirm().delete(userId);
+
+// Custom message
+await service.confirm('Are you sure you want to delete this user?').delete(userId);
+```
+
+> Uses `shRepo.runPlainRequest` from the SH Framework for native confirmation dialogs.
+
+### 7. Action URLs
+
+Generate fully qualified action URLs:
+
+#### Using `getActionUrl` from `useStreamline`
+
+```javascript
+const { getActionUrl } = useStreamline('reports');
+
+const downloadUrl = getActionUrl('download', reportId, 'pdf');
+// → https://your-api.com/streamline?action=download&stream=reports&params=reportId,pdf
+
+// Cross-stream actions
+const analyticsUrl = getActionUrl('analytics:trackEvent', eventName, eventData);
+```
+
+#### Using Standalone `getActionUrl`
+
+For scenarios where you only need URL generation without reactive state management:
+
+```vue
+<script setup>
+import { getActionUrl } from '@iankibetsh/vue-streamline';
+
+// Generate URLs directly
+const exportUrl = getActionUrl('users:export', userId, 'csv');
+const reportUrl = getActionUrl('reports:generate', reportId, 'pdf');
+</script>
+
+<template>
+  <!-- Use in templates -->
+  <a :href="getActionUrl('users:export', userId, 'csv')" download>
+    Export User
+  </a>
+  
+  <!-- Dynamic URLs -->
+  <div>
+    <h3>API Endpoint: {{ getActionUrl('users:listUsers', 'admin', 'active') }}</h3>
+  </div>
 </template>
 ```
-### Directly in your template
-In your template just access the props object to get the class properties. Prefer using computed to make it reactive
-```html
+
+**Benefits of Standalone Import:**
+- Lighter weight when you don't need reactive features
+- Can be used in utility files or non-component contexts
+- Still respects the global `streamlineUrl` configuration
+- Supports all the same features (cross-stream notation, multiple parameters)
+
+### 8. Cross-Stream Actions
+
+Execute actions on different streams using colon notation:
+
+```javascript
+const { service } = useStreamline('users');
+
+await service['analytics:trackEvent'](eventName, eventData);
+```
+
+## Advanced Usage
+
+### Immediate Property Access
+
+Access properties before loading — fetch triggers automatically:
+
+```javascript
+const { props } = useStreamline('dashboard', userId);
+
+watchEffect(() => {
+  console.log(props.stats); // Triggers fetch if needed
+});
+```
+
+### Error Handling
+
+All action calls return promises:
+
+```javascript
+const { service } = useStreamline('users');
+
+try {
+  const result = await service.create(userData);
+  console.log('User created:', result);
+} catch (error) {
+  console.error('Creation failed:', error);
+}
+```
+
+### Form Data Integration
+
+Pass structured data to actions:
+
+```javascript
+const { service } = useStreamline('posts');
+
+const formData = {
+  title: 'My Post',
+  content: 'Post content',
+  tags: ['vue', 'javascript']
+};
+
+await service.create(formData);
+```
+
+## Complete Example
+
+```vue
 <template>
-    <div>
-        <h1>{{props.title}}</h1>
+  <div class="user-management">
+    <div v-if="loading" class="loading">Loading...</div>
+    
+    <div v-else>
+      <h1>Total Users: {{ props.totalUsers }}</h1>
+      
+      <div class="users-list">
+        <div v-for="user in props.users" :key="user.id" class="user-card">
+          <h3>{{ user.name }}</h3>
+          <p>{{ user.email }}</p>
+          
+          <button @click="editUser(user)">Edit</button>
+          <button @click="deleteUser(user.id)">Delete</button>
+          
+          <a :href="getActionUrl('exportUser', user.id)" target="_blank" rel="noopener">
+            Export Profile
+          </a>
+        </div>
+      </div>
+      
+      <button @click="refreshData">Refresh</button>
+      <button @click="addNewUser">Add User</button>
     </div>
+  </div>
 </template>
+
+<script setup>
+import { useStreamline } from '@iankibetsh/vue-streamline';
+
+const { service, loading, props, getActionUrl } = useStreamline('users', 'active');
+
+const editUser = async (user) => {
+  try {
+    const result = await service.update(user.id, {
+      name: user.name,
+      email: user.email
+    });
+    console.log('User updated:', result);
+  } catch (error) {
+    console.error('Update failed:', error);
+  }
+};
+
+const deleteUser = async (userId) => {
+  try {
+    await service.confirm('Delete this user permanently?').delete(userId);
+    await service.refresh();
+  } catch (error) {
+    console.error('Delete failed:', error);
+  }
+};
+
+const refreshData = () => service.refresh();
+
+const addNewUser = async () => {
+  const newUser = { name: 'New User', email: 'newuser@example.com' };
+  await service.create(newUser);
+  await service.refresh();
+};
+</script>
+```
+
+## Best Practices
+
+1. **Use descriptive stream names** aligned with backend services.
+2. **Enable caching** for infrequently updated data.
+3. **Handle errors gracefully** in component logic.
+4. **Display loading states** for better user experience.
+5. **Use confirmation dialogs** for irreversible actions.
+6. **Leverage `getActionUrl`** for links and downloads.
+7. **Call `refresh()`** after mutations to synchronize UI.
+
+## `getActionUrl` Function Details
+
+```javascript
+const getActionUrl = (action, ...args) => {
+  let targetStream = stream;
+  let targetAction = action;
+
+  if (action.includes(':')) {
+    [targetStream, targetAction] = action.split(':');
+  }
+
+  const payload = {
+    action: targetAction,
+    stream: targetStream,
+    params: args
+  };
+
+  return `${streamlineUrl}?${new URLSearchParams(payload).toString()}`;
+};
 ```
+
+**Key Capabilities:**
+- Serializes arguments into query parameters.
+- Supports cross-stream routing via `stream:action`.
+- Produces ready-to-use, fully qualified URLs.
+
+## Dependencies
+
+- **Vue 3**: `reactive`, `ref`, `inject`, `onMounted`
+- **@iankibetsh/shframework**: `shApis`, `shRepo`
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
       "name": "@iankibetsh/vue-streamline",
-      "version": "1.3.0",
+      "version": "1.3.2",
       "description": "Vue library for streamlining laravel backend services with @iankibet/streamline composer package",
       "type": "module",
       "scripts": {

package/src/App.vue

@@ -1,6 +1,7 @@
 <script setup>
 import useStreamline from './composables/useStreamline.js'
 import { onMounted, ref, toRefs } from 'vue'
+import SimpleGetActionUrl from './SimpleGetActionUrl.vue'
 
 const {loading, service:paybillService, getActionUrl,props,confirmAction} = useStreamline('mpesa/paybill',true)
 
@@ -40,6 +41,7 @@ const refresh = ()=>{
     <h1 @click="refresh">Refresh</h1>
     {{ foundPaybill }}
   </div>
+  <simple-get-action-url/>
 </template>
 
 <style scoped>

package/src/SimpleGetActionUrl.vue

@@ -0,0 +1,11 @@
+<script setup>
+import getActionUrl from './composables/getActionUrl.js'
+</script>
+
+<template>
+<h3>Sample Action Url: {{ getActionUrl('users:listUsers','admin','active') }}</h3>
+</template>
+
+<style scoped>
+
+</style>

package/src/composables/getActionUrl.js

@@ -0,0 +1,7 @@
+import useStreamline from './useStreamline.js'
+
+
+export default function getActionUrl(actionSlug, ...args) {
+    const { getActionUrl } = useStreamline('')
+    return getActionUrl(actionSlug, ...args)
+}

package/src/index.js

@@ -1,6 +1,8 @@
 import useStreamline from './composables/useStreamline.js'
+import getActionUrl from './composables/getActionUrl.js'
 import streamline from './plugins/streamline.js'
 export {
     useStreamline,
+    getActionUrl,
     streamline
 }

package/src/plugins/streamline.js

@@ -1,6 +1,6 @@
 const streamline = {
     install(app, options) {
-        app.provide('streamlineUrl', options.streamlineUrl)
+        app.provide('streamlineUrl', options.streamlineUrl ?? '/api/streamline')
         // app.provide('streamlineHeaders', options.streamlineHeaders)
         app.provide('enableCache', options.enableCache)
     }