ap-laravel-ajax-helper 1.0.0 → 1.0.1

package/README.md

@@ -1,24 +1,46 @@
 # Laravel AJAX Helper
 
-A lightweight utility to simplify Laravel AJAX form requests with validation error handling.
+A lightweight JavaScript utility to simplify AJAX requests in Laravel applications. Handles CSRF protection, form data submission, and validation error display with minimal setup.
 
-## 🚀 Usage
+---
 
-### 📄 HTML Form Example
+## 🚀 Features
+
+* ✅ One-liner AJAX integration with Laravel routes
+* ✅ Automatically appends CSRF token from `<meta name="csrf-token">`
+* ✅ Displays validation errors in `.error-[field_name]` elements
+* ✅ Optional loading spinner with button text
+* ✅ Built for modern browsers and Laravel developers
+
+---
+
+## 📦 Installation
+
+```bash
+npm install laravel-ajax-helper
+```
+
+---
+
+## 📄 HTML Form Example
+
+Add proper `name` attributes to inputs and matching `.error-[field_name]` spans for error display.
 
 ```html
 <form id="loginForm">
   <input type="email" name="email" />
-  <span class="error-email text-red-500"></span>
+  <span class="error-email"></span>
 
   <input type="password" name="password" />
-  <span class="error-password text-red-500"></span>
+  <span class="error-password"></span>
 
   <button id="loginBtn">Login</button>
 </form>
 ```
 
-### 🧠 JavaScript Usage
+---
+
+## 🧠 JavaScript Usage
 
 ```js
 import laravelAjax from 'laravel-ajax-helper';
@@ -28,7 +50,8 @@ laravelAjax({
   method: 'POST',
   formId: 'loginForm',
   buttonId: 'loginBtn',
-  loadingText: 'Logging in...'
+  loadingText: 'Logging in...',
+  csrf: true // Will read from <meta name="csrf-token" content="...">
 })
   .then(response => {
     console.log('Success:', response);
@@ -38,45 +61,62 @@ laravelAjax({
   });
 ```
 
-## 🧰 Parameters
+---
+
+## ⚙️ Parameters
+
+| Parameter     | Type    | Required | Description                                                                   |
+| ------------- | ------- | -------- | ----------------------------------------------------------------------------- |
+| `url`         | string  | ✅ Yes    | Laravel route URL.                                                            |
+| `method`      | string  | ❌ No     | HTTP method: 'POST', 'GET', 'PUT', 'DELETE'. Defaults to `'POST'`.            |
+| `formId`      | string  | ✅ Yes    | HTML form ID (grabs data from inputs).                                        |
+| `buttonId`    | string  | ❌ No     | Button ID for loading state UX.                                               |
+| `loadingText` | string  | ❌ No     | Text to show with spinner while loading. Defaults to `'Loading...'`.          |
+| `csrf`        | boolean | ❌ No     | If `true`, automatically uses `<meta name="csrf-token">`. Defaults to `true`. |
+
+---
+
+## ❗️ CSRF Handling
+
+If `csrf: true` and no meta tag is found, the function will throw an error.
+
+Make sure your HTML includes:
+
+```html
+<meta name="csrf-token" content="{{ csrf_token() }}">
+```
 
-| Parameter     | Type   | Required | Description                                                          |
-| ------------- | ------ | -------- | -------------------------------------------------------------------- |
-| `url`         | string | ✅ Yes    | The Laravel route URL for the AJAX request.                          |
-| `method`      | string | ❌ No     | Request method: 'POST', 'GET', 'PUT', 'DELETE'. Default: 'POST'.     |
-| `formId`      | string | ✅ Yes    | ID of the form element (do not pass form data manually).             |
-| `buttonId`    | string | ❌ No     | ID of the button to show a loading spinner during request.           |
-| `loadingText` | string | ❌ No     | Text to show with spinner during the request. Default: 'Loading...'. |
+---
 
-## ❗ Error Handling
+## ⚠️ Error Handling
 
-* Laravel validation errors (422) are automatically displayed in elements with class `.error-[field_name]`.
+* **422 Validation Errors**: Automatically shown in `.error-[field_name]` spans.
+* **Other Errors (500, 403, etc.)**: Logged to console or returned via `.catch()`.
 
-  * **Example:** For field `email`, use `.error-email`
-* On other errors (like 500), a generic error is returned.
+---
 
-## 📁 File Structure (Simplified)
+## 📁 File Structure
 
 ```
 laravel-ajax-helper/
-├── dist/
-│   └── index.js         # Transpiled output
+├── dist/        # Compiled code
 ├── src/
-│   └── index.js         # Main AJAX function
+│   └── index.js         # Core logic
 ├── README.md
 ├── LICENSE
 ├── package.json
 ```
 
-## 🪪 License
+---
 
-This project is licensed under the [MIT License](./LICENSE).
+## 🗪 License
 
-## 🙌 Contributing
+Licensed under the MIT License.
 
-Pull requests are welcome! Feel free to open issues or suggest improvements.
+---
 
 ## 💬 Author
 
-Akash Ap – [@akashap](https://github.com/aakashap01)
-Built with ❤️ for Laravel developers.
+**Akash Ap**
+Built with ❤️ for Laravel developers
+GitHub: [@aakashap01](https://github.com/aakashap01)

package/dist/laravel-ajax.cjs.js

@@ -0,0 +1,105 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  default: () => laravelAjax
+});
+module.exports = __toCommonJS(index_exports);
+function laravelAjax({
+  url,
+  method = "POST",
+  formId,
+  buttonId = null,
+  loadingText = "Loading...",
+  csrf = false,
+  // << true to auto-fetch from meta tag
+  onSuccess = null,
+  onError = null
+}) {
+  return new Promise((resolve, reject) => {
+    if (!url) return reject({ error: "URL is required." });
+    if (!formId) return reject({ error: "formId is required." });
+    const form = document.getElementById(formId);
+    if (!form) return reject({ error: `Form with ID "${formId}" not found.` });
+    form.addEventListener("submit", (e) => e.preventDefault());
+    const formData = new FormData(form);
+    const btn = buttonId ? document.getElementById(buttonId) : null;
+    const originalBtnText = btn ? btn.innerHTML : null;
+    if (btn) {
+      btn.disabled = true;
+      btn.innerHTML = `<span class="spinner-border spinner-border-sm me-2"></span>${loadingText}`;
+    }
+    document.querySelectorAll('[class^="error-"]').forEach((el) => {
+      if (["DIV", "SPAN"].includes(el.tagName)) el.innerText = "";
+    });
+    const headers = {};
+    if (csrf) {
+      const tokenTag = document.querySelector('meta[name="csrf-token"]');
+      if (!tokenTag) {
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+        return reject({
+          error: `CSRF token not found. Please add <meta name="csrf-token" content="..."> in <head>.`
+        });
+      }
+      headers["X-CSRF-TOKEN"] = tokenTag.getAttribute("content");
+    }
+    $.ajax({
+      url,
+      method,
+      data: formData,
+      headers,
+      contentType: false,
+      processData: false,
+      cache: false,
+      success: function(response) {
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+        if (typeof onSuccess === "function") onSuccess(response);
+        resolve(response);
+      },
+      error: function(xhr) {
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+        if (xhr.status === 422 && xhr.responseJSON?.errors) {
+          const errors = xhr.responseJSON.errors;
+          for (const field in errors) {
+            const el = document.querySelector(`.error-${field}`);
+            if (el && ["DIV", "SPAN"].includes(el.tagName)) {
+              el.innerText = errors[field][0];
+            }
+          }
+          if (typeof onError === "function") onError(errors);
+          reject(errors);
+        } else {
+          const fallbackError = { error: "Unexpected error occurred." };
+          if (typeof onError === "function") onError(fallbackError);
+          reject(fallbackError);
+        }
+      }
+    });
+  });
+}

package/dist/laravel-ajax.esm.js

@@ -0,0 +1,85 @@
+// src/index.js
+function laravelAjax({
+  url,
+  method = "POST",
+  formId,
+  buttonId = null,
+  loadingText = "Loading...",
+  csrf = false,
+  // << true to auto-fetch from meta tag
+  onSuccess = null,
+  onError = null
+}) {
+  return new Promise((resolve, reject) => {
+    if (!url) return reject({ error: "URL is required." });
+    if (!formId) return reject({ error: "formId is required." });
+    const form = document.getElementById(formId);
+    if (!form) return reject({ error: `Form with ID "${formId}" not found.` });
+    form.addEventListener("submit", (e) => e.preventDefault());
+    const formData = new FormData(form);
+    const btn = buttonId ? document.getElementById(buttonId) : null;
+    const originalBtnText = btn ? btn.innerHTML : null;
+    if (btn) {
+      btn.disabled = true;
+      btn.innerHTML = `<span class="spinner-border spinner-border-sm me-2"></span>${loadingText}`;
+    }
+    document.querySelectorAll('[class^="error-"]').forEach((el) => {
+      if (["DIV", "SPAN"].includes(el.tagName)) el.innerText = "";
+    });
+    const headers = {};
+    if (csrf) {
+      const tokenTag = document.querySelector('meta[name="csrf-token"]');
+      if (!tokenTag) {
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+        return reject({
+          error: `CSRF token not found. Please add <meta name="csrf-token" content="..."> in <head>.`
+        });
+      }
+      headers["X-CSRF-TOKEN"] = tokenTag.getAttribute("content");
+    }
+    $.ajax({
+      url,
+      method,
+      data: formData,
+      headers,
+      contentType: false,
+      processData: false,
+      cache: false,
+      success: function(response) {
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+        if (typeof onSuccess === "function") onSuccess(response);
+        resolve(response);
+      },
+      error: function(xhr) {
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+        if (xhr.status === 422 && xhr.responseJSON?.errors) {
+          const errors = xhr.responseJSON.errors;
+          for (const field in errors) {
+            const el = document.querySelector(`.error-${field}`);
+            if (el && ["DIV", "SPAN"].includes(el.tagName)) {
+              el.innerText = errors[field][0];
+            }
+          }
+          if (typeof onError === "function") onError(errors);
+          reject(errors);
+        } else {
+          const fallbackError = { error: "Unexpected error occurred." };
+          if (typeof onError === "function") onError(fallbackError);
+          reject(fallbackError);
+        }
+      }
+    });
+  });
+}
+export {
+  laravelAjax as default
+};

package/dist/laravel-ajax.min.js

@@ -0,0 +1 @@
+var laravelAjax=(()=>{var m=Object.defineProperty;var D=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var q=(t,r)=>{for(var o in r)m(t,o,{get:r[o],enumerable:!0})},x=(t,r,o,f)=>{if(r&&typeof r=="object"||typeof r=="function")for(let s of N(r))!k.call(t,s)&&s!==o&&m(t,s,{get:()=>r[s],enumerable:!(f=D(r,s))||f.enumerable});return t};var A=t=>x(m({},"__esModule",{value:!0}),t);var H={};q(H,{default:()=>y});function y({url:t,method:r="POST",formId:o,buttonId:f=null,loadingText:s="Loading...",csrf:S=!1,onSuccess:p=null,onError:l=null}){return new Promise((g,i)=>{if(!t)return i({error:"URL is required."});if(!o)return i({error:"formId is required."});let c=document.getElementById(o);if(!c)return i({error:`Form with ID "${o}" not found.`});c.addEventListener("submit",n=>n.preventDefault());let L=new FormData(c),e=f?document.getElementById(f):null,u=e?e.innerHTML:null;e&&(e.disabled=!0,e.innerHTML=`<span class="spinner-border spinner-border-sm me-2"></span>${s}`),document.querySelectorAll('[class^="error-"]').forEach(n=>{["DIV","SPAN"].includes(n.tagName)&&(n.innerText="")});let T={};if(S){let n=document.querySelector('meta[name="csrf-token"]');if(!n)return e&&(e.disabled=!1,e.innerHTML=u),i({error:'CSRF token not found. Please add <meta name="csrf-token" content="..."> in <head>.'});T["X-CSRF-TOKEN"]=n.getAttribute("content")}$.ajax({url:t,method:r,data:L,headers:T,contentType:!1,processData:!1,cache:!1,success:function(n){e&&(e.disabled=!1,e.innerHTML=u),typeof p=="function"&&p(n),g(n)},error:function(n){if(e&&(e.disabled=!1,e.innerHTML=u),n.status===422&&n.responseJSON?.errors){let a=n.responseJSON.errors;for(let b in a){let d=document.querySelector(`.error-${b}`);d&&["DIV","SPAN"].includes(d.tagName)&&(d.innerText=a[b][0])}typeof l=="function"&&l(a),i(a)}else{let a={error:"Unexpected error occurred."};typeof l=="function"&&l(a),i(a)}}})})}return A(H);})();

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "ap-laravel-ajax-helper",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A lightweight JavaScript utility for Laravel-style AJAX requests.",
-  "main": "dist/index.js",
-  "module": "dist/index.esm.js",
+  "main": "dist/laravel-ajax.cjs.js",
+  "module": "dist/laravel-ajax.esm.js",
+  "browser": "dist/laravel-ajax.min.js",
+  "exports": {
+    "import": "./dist/laravel-ajax.esm.js",
+    "require": "./dist/laravel-ajax.cjs.js",
+    "default": "./dist/laravel-ajax.min.js"
+  },
   "scripts": {
-    "build": "babel src --out-dir dist"
+    "build": "esbuild src/index.js --bundle --minify --format=iife --global-name=laravelAjax --outfile=dist/laravel-ajax.min.js && esbuild src/index.js --bundle --format=cjs --outfile=dist/laravel-ajax.cjs.js && esbuild src/index.js --bundle --format=esm --outfile=dist/laravel-ajax.esm.js"
   },
-  "author": "AkashAp",
-  "license": "MIT",
   "keywords": [
     "laravel",
     "ajax",
@@ -16,10 +20,13 @@
     "validation",
     "jquery"
   ],
+  "author": "AkashAp",
+  "license": "MIT",
   "devDependencies": {
     "@babel/cli": "^7.28.0",
     "@babel/core": "^7.28.0",
     "@babel/preset-env": "^7.28.0",
+    "esbuild": "^0.25.8",
     "rollup": "^3.0.0"
   },
   "peerDependencies": {
@@ -30,5 +37,13 @@
     "src/",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aakashap01/ap-laravel-ajax-helper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aakashap01/ap-laravel-ajax-helper/issues"
+  },
+  "homepage": "https://github.com/aakashap01/ap-laravel-ajax-helper#readme"
 }

package/src/index.js

@@ -1,9 +1,12 @@
 export default function laravelAjax({
   url,
   method = 'POST',
-  formId = null,
+  formId,
   buttonId = null,
   loadingText = 'Loading...',
+  csrf = false, // << true to auto-fetch from meta tag
+  onSuccess = null,
+  onError = null,
 }) {
   return new Promise((resolve, reject) => {
     if (!url) return reject({ error: 'URL is required.' });
@@ -12,55 +15,77 @@ export default function laravelAjax({
     const form = document.getElementById(formId);
     if (!form) return reject({ error: `Form with ID "${formId}" not found.` });
 
-    const formData = new FormData(form);
+    // Prevent default form submission
+    form.addEventListener('submit', (e) => e.preventDefault());
 
+    const formData = new FormData(form);
     const btn = buttonId ? document.getElementById(buttonId) : null;
-    const originalButtonText = btn ? btn.innerHTML : null;
+    const originalBtnText = btn ? btn.innerHTML : null;
 
-    // Disable and show loading on button
+    // Disable button and show loading text
     if (btn) {
       btn.disabled = true;
       btn.innerHTML = `<span class="spinner-border spinner-border-sm me-2"></span>${loadingText}`;
     }
 
-    // Clear all validation error messages
+    // Clear previous validation errors
     document.querySelectorAll('[class^="error-"]').forEach((el) => {
-      if (el.tagName === 'DIV' || el.tagName === 'SPAN') {
-        el.innerText = '';
-      }
+      if (['DIV', 'SPAN'].includes(el.tagName)) el.innerText = '';
     });
 
+    // Prepare headers
+    const headers = {};
+    if (csrf) {
+      const tokenTag = document.querySelector('meta[name="csrf-token"]');
+      if (!tokenTag) {
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+        return reject({
+          error: `CSRF token not found. Please add <meta name="csrf-token" content="..."> in <head>.`,
+        });
+      }
+      headers['X-CSRF-TOKEN'] = tokenTag.getAttribute('content');
+    }
+
+    // Perform AJAX request
     $.ajax({
       url,
       method,
       data: formData,
+      headers,
       contentType: false,
       processData: false,
       cache: false,
       success: function (response) {
         if (btn) {
-          btn.innerHTML = originalButtonText;
           btn.disabled = false;
+          btn.innerHTML = originalBtnText;
         }
+        if (typeof onSuccess === 'function') onSuccess(response);
         resolve(response);
       },
       error: function (xhr) {
-        if (xhr.status === 422) {
-          const errors = xhr.responseJSON?.errors || {};
+        if (btn) {
+          btn.disabled = false;
+          btn.innerHTML = originalBtnText;
+        }
+
+        if (xhr.status === 422 && xhr.responseJSON?.errors) {
+          const errors = xhr.responseJSON.errors;
           for (const field in errors) {
-            const target = document.querySelector(`.error-${field}`);
-            if (target && (target.tagName === 'DIV' || target.tagName === 'SPAN')) {
-              target.innerText = errors[field][0];
+            const el = document.querySelector(`.error-${field}`);
+            if (el && ['DIV', 'SPAN'].includes(el.tagName)) {
+              el.innerText = errors[field][0];
             }
           }
+          if (typeof onError === 'function') onError(errors);
           reject(errors);
         } else {
-          reject({ error: 'Unexpected error occurred.' });
-        }
-
-        if (btn) {
-          btn.innerHTML = originalButtonText;
-          btn.disabled = false;
+          const fallbackError = { error: 'Unexpected error occurred.' };
+          if (typeof onError === 'function') onError(fallbackError);
+          reject(fallbackError);
         }
       },
     });

package/dist/index.js

@@ -1,81 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports["default"] = laravelAjax;
-function laravelAjax(_ref) {
-  var url = _ref.url,
-    _ref$method = _ref.method,
-    method = _ref$method === void 0 ? 'POST' : _ref$method,
-    _ref$formId = _ref.formId,
-    formId = _ref$formId === void 0 ? null : _ref$formId,
-    _ref$buttonId = _ref.buttonId,
-    buttonId = _ref$buttonId === void 0 ? null : _ref$buttonId,
-    _ref$loadingText = _ref.loadingText,
-    loadingText = _ref$loadingText === void 0 ? 'Loading...' : _ref$loadingText;
-  return new Promise(function (resolve, reject) {
-    if (!url) return reject({
-      error: 'URL is required.'
-    });
-    if (!formId) return reject({
-      error: 'formId is required.'
-    });
-    var form = document.getElementById(formId);
-    if (!form) return reject({
-      error: "Form with ID \"".concat(formId, "\" not found.")
-    });
-    var formData = new FormData(form);
-    var btn = buttonId ? document.getElementById(buttonId) : null;
-    var originalButtonText = btn ? btn.innerHTML : null;
-
-    // Disable and show loading on button
-    if (btn) {
-      btn.disabled = true;
-      btn.innerHTML = "<span class=\"spinner-border spinner-border-sm me-2\"></span>".concat(loadingText);
-    }
-
-    // Clear all validation error messages
-    document.querySelectorAll('[class^="error-"]').forEach(function (el) {
-      if (el.tagName === 'DIV' || el.tagName === 'SPAN') {
-        el.innerText = '';
-      }
-    });
-    $.ajax({
-      url: url,
-      method: method,
-      data: formData,
-      contentType: false,
-      processData: false,
-      cache: false,
-      success: function success(response) {
-        if (btn) {
-          btn.innerHTML = originalButtonText;
-          btn.disabled = false;
-        }
-        resolve(response);
-      },
-      error: function error(xhr) {
-        if (xhr.status === 422) {
-          var _xhr$responseJSON;
-          var errors = ((_xhr$responseJSON = xhr.responseJSON) === null || _xhr$responseJSON === void 0 ? void 0 : _xhr$responseJSON.errors) || {};
-          for (var field in errors) {
-            var target = document.querySelector(".error-".concat(field));
-            if (target && (target.tagName === 'DIV' || target.tagName === 'SPAN')) {
-              target.innerText = errors[field][0];
-            }
-          }
-          reject(errors);
-        } else {
-          reject({
-            error: 'Unexpected error occurred.'
-          });
-        }
-        if (btn) {
-          btn.innerHTML = originalButtonText;
-          btn.disabled = false;
-        }
-      }
-    });
-  });
-}