@provydon/vue-auto-save 1.0.0

package/README.md

@@ -0,0 +1,264 @@
+# useAutoSaveForm
+
+A powerful Vue 3 composable that automatically saves form data with intelligent debouncing, field filtering, and lifecycle hooks.
+
+[![npm version](https://img.shields.io/npm/v/@provydon/vue-auto-save.svg)](https://www.npmjs.com/package/@provydon/vue-auto-save)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- 🚀 **Auto-save on change** with configurable debounce
+- 🎯 **Smart field filtering** - skip Inertia helpers or custom fields
+- 🛡️ **Blockable watchers** - pause auto-save during initialization
+- 🔄 **Lifecycle hooks** - beforeSave, afterSave, onError callbacks
+- 🎛️ **Custom serialization** - support for circular references and functions
+- 🧪 **Custom comparators** - shallow/deep equality without stringification
+- 🧹 **Automatic cleanup** - no memory leaks on component unmount
+- 📦 **Framework agnostic** - works with Axios, Inertia, Fetch, etc.
+
+## 🚀 Quick Start
+
+```bash
+npm install @provydon/vue-auto-save
+```
+
+```vue
+<script setup>
+import { reactive } from 'vue'
+import { useAutoSaveForm } from '@provydon/vue-auto-save'
+
+const form = reactive({
+  title: '',
+  content: '',
+  tags: []
+})
+
+const { isAutoSaving } = useAutoSaveForm(form, {
+  onSave: async () => {
+    await axios.post('/api/posts', form)
+  },
+  debounce: 2000,
+  debug: true
+})
+</script>
+
+<template>
+  <form>
+    <input v-model="form.title" placeholder="Post title" />
+    <textarea v-model="form.content" placeholder="Post content" />
+    <div v-if="isAutoSaving">Saving...</div>
+  </form>
+</template>
+```
+
+## 📖 API Reference
+
+### Basic Usage
+
+```ts
+const { isAutoSaving, blockWatcher, unblockWatcher, stop } = useAutoSaveForm(
+  form, // reactive object or ref
+  options
+)
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `onSave` | `() => void \| Promise<void>` | **Required** | Function called when auto-save should trigger |
+| `debounce` | `number` | `3000` | Delay in milliseconds before saving |
+| `skipFields` | `string[]` | `[]` | Field names to exclude from tracking |
+| `skipInertiaFields` | `boolean` | `true` | Skip common Inertia.js form helpers |
+| `deep` | `boolean` | `true` | Deep watch the form object |
+| `debug` | `boolean` | `false` | Enable console logging |
+| `saveOnInit` | `boolean` | `false` | Save immediately on mount |
+| `serialize` | `(obj) => string` | `JSON.stringify` | Custom serialization function |
+| `compare` | `(a, b) => boolean` | `undefined` | Custom comparison function |
+| `onBeforeSave` | `() => void` | `undefined` | Called before saving |
+| `onAfterSave` | `() => void` | `undefined` | Called after successful save |
+| `onError` | `(err) => void` | `undefined` | Called on save error |
+
+### Return Values
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isAutoSaving` | `Ref<boolean>` | Reactive boolean indicating save status |
+| `blockWatcher` | `(ms?: number) => void` | Temporarily block auto-save |
+| `unblockWatcher` | `(ms?: number \| null) => void` | Unblock and optionally save immediately |
+| `stop` | `() => void` | Manually stop the watcher |
+
+## 🎯 Examples
+
+### With Inertia.js
+
+```ts
+import { useForm } from '@inertiajs/vue3'
+import { useAutoSaveForm } from '@provydon/vue-auto-save'
+
+const form = useForm({
+  title: '',
+  content: '',
+  published: false
+})
+
+const { isAutoSaving } = useAutoSaveForm(form, {
+  onSave: () => form.post('/posts', { preserveState: true }),
+  skipInertiaFields: true, // Skips processing, errors, etc.
+  debounce: 1000
+})
+```
+
+### Custom Serialization
+
+```ts
+const { isAutoSaving } = useAutoSaveForm(form, {
+  onSave: saveToAPI,
+  serialize: (obj) => {
+    // Handle circular references or functions
+    return JSON.stringify(obj, (key, value) => {
+      if (typeof value === 'function') return '[Function]'
+      return value
+    })
+  }
+})
+```
+
+### Custom Comparator
+
+```ts
+import { isEqual } from 'lodash-es'
+
+const { isAutoSaving } = useAutoSaveForm(form, {
+  onSave: saveToAPI,
+  compare: (a, b) => isEqual(a, b), // Deep equality without stringification
+  serialize: undefined // Not used when compare is provided
+})
+```
+
+### Block During Initialization
+
+```ts
+const { isAutoSaving, blockWatcher } = useAutoSaveForm(form, {
+  onSave: saveToAPI,
+  saveOnInit: false
+})
+
+// Block auto-save during form initialization
+blockWatcher(5000) // Block for 5 seconds
+
+// Or block indefinitely and unblock manually
+blockWatcher()
+// ... do initialization work ...
+unblockWatcher() // Resume auto-save
+```
+
+### With Ref Forms
+
+```ts
+const form = ref({
+  name: '',
+  email: ''
+})
+
+const { isAutoSaving } = useAutoSaveForm(form, {
+  onSave: saveToAPI
+})
+```
+
+## 🔧 Advanced Usage
+
+### Lifecycle Hooks
+
+```ts
+const { isAutoSaving } = useAutoSaveForm(form, {
+  onSave: saveToAPI,
+  onBeforeSave: () => {
+    console.log('About to save...')
+  },
+  onAfterSave: () => {
+    console.log('Save completed!')
+  },
+  onError: (error) => {
+    console.error('Save failed:', error)
+  }
+})
+```
+
+### Manual Control
+
+```ts
+const { isAutoSaving, stop } = useAutoSaveForm(form, {
+  onSave: saveToAPI
+})
+
+// Manually stop the watcher
+stop()
+
+// The watcher will also stop automatically on component unmount
+```
+
+## 🎨 Styling Examples
+
+### Loading Indicator
+
+```vue
+<template>
+  <div class="form-container">
+    <input v-model="form.title" />
+    <div v-if="isAutoSaving" class="save-indicator">
+      <span class="spinner"></span>
+      Auto-saving...
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.save-indicator {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: #666;
+  font-size: 14px;
+}
+
+.spinner {
+  width: 16px;
+  height: 16px;
+  border: 2px solid #ddd;
+  border-top: 2px solid #007bff;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  0% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}
+</style>
+```
+
+## 🚨 Important Notes
+
+- **Circular References**: `JSON.stringify` (default serializer) will throw on circular references. Use a custom `serialize` function if needed.
+- **Functions**: Functions won't survive `JSON.stringify`. Use custom serialization for function-heavy forms.
+- **Vue Version**: Requires Vue 3.2+ (supports both reactive objects and refs).
+- **Cleanup**: Watchers and timers are automatically cleaned up on component unmount.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT © [Providence Ifeosame](https://github.com/provydon)
+
+## 🙏 Support
+
+If you find this package helpful, consider:
+- ⭐ Starring the repository
+- 🐛 Reporting bugs
+- 💡 Suggesting features
+- ☕ [Buying me a coffee](https://buymeacoffee.com/provydon)
+
+Follow me on [Twitter](https://x.com/ProvyDon1) or connect on [LinkedIn](https://www.linkedin.com/in/providence-ifeosame/).

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { Ref } from 'vue';
+export interface UseAutoSaveFormOptions {
+    /**
+     * Delay in milliseconds before auto-saving after changes (default: 3000ms)
+     */
+    debounce?: number;
+    /**
+     * List of form field keys to exclude from tracking
+     */
+    skipFields?: string[];
+    /**
+     * Whether to skip common Inertia form fields (default: true)
+     */
+    skipInertiaFields?: boolean;
+    /**
+     * Whether to deeply watch the form (default: true)
+     */
+    deep?: boolean;
+    /**
+     * Enable debug logs in the console (default: false)
+     */
+    debug?: boolean;
+    /**
+     * Custom serializer function (default: JSON.stringify)
+     * Note: Functions and non-serializable fields won't survive JSON.stringify.
+     * Circular references will also cause JSON.stringify to throw.
+     * Use a custom serializer if you need to handle these cases.
+     */
+    serialize?: (obj: Record<string, unknown>) => string;
+    /**
+     * Custom comparator function (optional)
+     * If provided, this will be used instead of string comparison
+     */
+    compare?: (a: Record<string, unknown>, b: Record<string, unknown>) => boolean;
+    /**
+     * Whether to save on initial mount (default: false)
+     */
+    saveOnInit?: boolean;
+    /**
+     * Called when a save should be triggered (required)
+     */
+    onSave: () => void | Promise<void>;
+    /**
+     * Called just before auto-saving starts
+     */
+    onBeforeSave?: () => void;
+    /**
+     * Called after a successful auto-save
+     */
+    onAfterSave?: () => void;
+    /**
+     * Called if auto-saving throws or fails
+     */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Automatically watches a Vue 3 form object and triggers save on change with debounce.
+ * Includes support for skipping specific fields and Inertia form helpers.
+ *
+ * @param form - The form object to watch (typically a reactive or ref object)
+ * @param options - Configuration for debounce, lifecycle hooks, and field skipping
+ * @returns An object with `isAutoSaving` and `blockWatcher()` for temporary disable
+ */
+export declare function useAutoSaveForm(form: Record<string, unknown> | Ref<Record<string, unknown>>, options: UseAutoSaveFormOptions): {
+    isAutoSaving: Ref<boolean, boolean>;
+    blockWatcher: (ms?: number) => void;
+    unblockWatcher: (ms?: number | null) => void;
+    stop: import('vue').WatchHandle;
+};

package/dist/useAutoSaveForm.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("vue"),P=["save","applicationId","isDirty","processing","errors","hasErrors","recentlySuccessful","wasSuccessful","data","transform","get","post","put","patch","delete","cancel","reset","clearErrors","setError","setData"];function q(l,p){const{debounce:n=3e3,skipFields:T=[],skipInertiaFields:I=!0,deep:O=!0,debug:o=!1,serialize:D=JSON.stringify,compare:S,saveOnInit:b=!1,onSave:W,onBeforeSave:h,onAfterSave:m,onError:c}=p,u=s.ref(!1),a=s.ref(!0);let r=()=>{},i=()=>{};const j=(t=1e3)=>{a.value=!1,r(),i(),setTimeout(()=>{a.value=!0},t)},z=(t=null)=>{if(a.value=!0,r(),i(),t===null)d();else{const e=A(d,t);i=e.cancel,e.call()}},f=()=>{const t=s.isRef(l)?s.unref(l):l,e={};for(const v of Object.keys(t))I&&P.includes(v)||T.includes(v)||(e[v]=t[v]);return e};let g=b?null:D(f()),y=S?b?null:f():null;const d=()=>{if(!a.value)return;const t=f();if(S){if(y&&S(y,t))return;y=t}else{const e=D(t);if(g!==null&&e===g)return;g=e}o&&console.log("[AutoSave] Detected changes. Saving..."),u.value=!0;try{h==null||h(),Promise.resolve(W()).then(()=>{m==null||m(),o&&console.log("[AutoSave] Save successful.")}).catch(e=>{c==null||c(e),o&&console.error("[AutoSave] Save failed:",e)}).finally(()=>{u.value=!1})}catch(e){c==null||c(e),o&&console.error("[AutoSave] Immediate error:",e),u.value=!1}},F=A(d,n),w=F.call;r=F.cancel;const k=s.watch(()=>f(),w,{deep:O,flush:"post"});return s.onScopeDispose(()=>{k(),r(),i()}),b&&d(),{isAutoSaving:u,blockWatcher:j,unblockWatcher:z,stop:k}}function A(l,p){let n;return{call:()=>{clearTimeout(n),n=setTimeout(()=>l(),p)},cancel:()=>{clearTimeout(n)}}}exports.useAutoSaveForm=q;

package/dist/useAutoSaveForm.mjs

@@ -0,0 +1,115 @@
+import { ref as F, watch as x, onScopeDispose as J, isRef as N, unref as P } from "vue";
+const R = [
+  "save",
+  "applicationId",
+  "isDirty",
+  "processing",
+  "errors",
+  "hasErrors",
+  "recentlySuccessful",
+  "wasSuccessful",
+  "data",
+  "transform",
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "cancel",
+  "reset",
+  "clearErrors",
+  "setError",
+  "setData"
+];
+function C(s, v) {
+  const {
+    debounce: l = 3e3,
+    skipFields: I = [],
+    skipInertiaFields: T = !0,
+    deep: O = !0,
+    debug: n = !1,
+    serialize: y = JSON.stringify,
+    compare: p,
+    saveOnInit: S = !1,
+    onSave: W,
+    onBeforeSave: h,
+    onAfterSave: m,
+    onError: c
+  } = v, o = F(!1), a = F(!0);
+  let u = () => {
+  }, r = () => {
+  };
+  const z = (t = 1e3) => {
+    a.value = !1, u(), r(), setTimeout(() => {
+      a.value = !0;
+    }, t);
+  }, j = (t = null) => {
+    if (a.value = !0, u(), r(), t === null)
+      f();
+    else {
+      const e = A(f, t);
+      r = e.cancel, e.call();
+    }
+  }, i = () => {
+    const t = N(s) ? P(s) : s, e = {};
+    for (const d of Object.keys(t))
+      T && R.includes(d) || I.includes(d) || (e[d] = t[d]);
+    return e;
+  };
+  let b = S ? null : y(i()), g = p ? S ? null : i() : null;
+  const f = () => {
+    if (!a.value) return;
+    const t = i();
+    if (p) {
+      if (g && p(g, t)) return;
+      g = t;
+    } else {
+      const e = y(t);
+      if (b !== null && e === b) return;
+      b = e;
+    }
+    n && console.log("[AutoSave] Detected changes. Saving..."), o.value = !0;
+    try {
+      h == null || h(), Promise.resolve(W()).then(() => {
+        m == null || m(), n && console.log("[AutoSave] Save successful.");
+      }).catch((e) => {
+        c == null || c(e), n && console.error("[AutoSave] Save failed:", e);
+      }).finally(() => {
+        o.value = !1;
+      });
+    } catch (e) {
+      c == null || c(e), n && console.error("[AutoSave] Immediate error:", e), o.value = !1;
+    }
+  }, D = A(f, l), w = D.call;
+  u = D.cancel;
+  const k = x(
+    () => i(),
+    w,
+    {
+      deep: O,
+      flush: "post"
+    }
+  );
+  return J(() => {
+    k(), u(), r();
+  }), S && f(), {
+    isAutoSaving: o,
+    blockWatcher: z,
+    unblockWatcher: j,
+    stop: k
+  };
+}
+function A(s, v) {
+  let l;
+  return {
+    call: () => {
+      clearTimeout(l), l = setTimeout(() => s(), v);
+    },
+    cancel: () => {
+      clearTimeout(l);
+    }
+  };
+}
+export {
+  C as useAutoSaveForm
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@provydon/vue-auto-save",
+  "version": "1.0.0",
+  "description": "A Vue 3 composable that autosaves forms with debounce, optional field skipping, and blockable watchers.",
+  "main": "./dist/useAutoSaveForm.cjs",
+  "module": "./dist/useAutoSaveForm.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/useAutoSaveForm.mjs",
+      "require": "./dist/useAutoSaveForm.cjs"
+    }
+  },
+  "files": ["dist"],
+  "keywords": ["vue", "composable", "autosave", "form", "debounce", "vue3"],
+  "author": "Providence Ifeosame",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/provydon/vue-auto-save.git"
+  },
+  "bugs": {
+    "url": "https://github.com/provydon/vue-auto-save/issues"
+  },
+  "homepage": "https://github.com/provydon/vue-auto-save#readme",
+  "sideEffects": false,
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "clean": "rm -rf dist",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "vue": "^3.5.18",
+    "typescript": "^5.9.2",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4",
+    "@vue/test-utils": "^2.4.5",
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^25.0.1"
+  }
+}