@ravishranjan/cart 2.0.8 → 2.1.0

package/README.md

@@ -1,14 +1,199 @@
 # @ravishranjan/cart
 
-A **native frontend cart system** with optional React hooks.  
-- Works in **any JavaScript app** (vanilla JS, Vue, Svelte, etc.)  
-- Provides **React hooks** for easy integration in React apps  
-- Stores cart data in **localStorage** or **sessionStorage**  
-- **No backend required**  
+A **lightweight, native frontend cart system** with optional **React hooks**.
+
+-   🧠 Works in **any JavaScript framework** — Vanilla JS, React, Vue, Svelte, etc.
+-   ⚛️ Includes **React hooks** and `<CartProvider>` for easy React integration.
+-   💾 Uses **localStorage** or **sessionStorage** for persistence.
+-   🔌 Works both via **npm install** and **CDN** — no backend required.
 
 ---
 
 ## 📦 Installation
 
+### Option 1 — NPM
+
 ```bash
 npm install @ravishranjan/cart
+```
+
+### Option 2 — CDN (no install)
+
+Use directly in your webpage:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ravishranjan/cart/dist/cart.min.js"></script>
+```
+---
+## Cart item type
+```ts
+interface CartItem {
+	id: string | number;
+	name: string;
+	price?: number;
+	quantity?: number;
+	category?: string;
+	[key: string]: any;
+}
+``` 
+
+---
+## 🧩 Usage Examples
+
+### **1️⃣ Basic JavaScript (no framework)**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ravishranjan/cart/dist/cart.min.js"></script>
+<script>
+	const cart = new Cart({ storage: "localStorage" });
+
+	cart.addItem({ id: 1, name: "Apple", price: 30, quantity: 2 });
+	cart.addItem({ id: 2, name: "Orange", price: 25 });
+
+	cart.removeItem(2);
+
+	console.log("Total price:", cart.getTotal());
+	console.log(cart.getItems());
+
+	cart.clear();
+</script>
+```
+
+---
+
+### **2️⃣ Node or Framework Projects (NPM install)**
+
+```js
+import Cart from "@ravishranjan/cart";
+
+const cart = new Cart({ storage: "localStorage" });
+
+cart.addItem({ id: 101, name: "Book", price: 199 });
+cart.addItem({ id: 102, name: "Pen", price: 49, quantity: 2 });
+
+console.log(cart.getItems());
+console.log("Total Price:", cart.getTotal());
+```
+
+**Available methods:**
+| Method | Description | Example |
+|---------|--------------|----------|
+| `addItem(item)` | Adds an item object | `cart.addItem({ id: 1, name: 'Apple', quantity: 2 })` |
+| `removeItem(id)` | Removes an item by id | `cart.removeItem(1)` |
+| `getItems()` | Returns all items | `cart.getItems()` |
+| `getItems(category)` | Returns items by given catefory | `cart.getItems("<category>")` |
+| `getTotal()` | Sum of all item prices × qty | `cart.getTotal()` |
+| `clear()` | Clears the entire cart | `cart.clear()` |
+
+---
+
+### **3️⃣ React Usage (with hooks + context)**
+
+#### Setup the Provider
+
+```tsx
+import React from "react";
+import { CartProvider } from "@ravishranjan/cart/react";
+
+import App from "./App";
+
+export default function Root() {
+	return (
+		<CartProvider storage="localStorage">
+			<App />
+		</CartProvider>
+	);
+}
+```
+
+#### Use the Hook
+
+```tsx
+import { useCart } from "@ravishranjan/cart/react";
+
+export default function Shop() {
+	const { items, addItem, removeItem, getTotal, clear } = useCart();
+
+	return (
+		<div>
+			<button
+				onClick={() => addItem({ id: 1, name: "Apple", price: 30 })}
+			>
+				Add Apple
+			</button>
+			<button onClick={() => clear()}>Clear Cart</button>
+
+			<ul>
+				{items.map((item) => (
+					<li key={item.id}>
+						{item.name} - ₹{item.price}
+						<button onClick={() => removeItem(item.id)}>❌</button>
+					</li>
+				))}
+			</ul>
+
+			<h3>Total: ₹{getTotal()}</h3>
+		</div>
+	);
+}
+```
+
+---
+
+## ⚙️ Storage Options
+
+| Option      | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| `"localStorage"`   | Persists cart across browser sessions (via localStorage) |
+| `"sessionStorage"` | Clears cart when the tab is closed (via sessionStorage)  |
+
+Usage:
+
+```js
+const cart = new Cart({ storage: "sessionStorage" });
+```
+
+or in React:
+
+```tsx
+<CartProvider storage="sessionStorage">
+	<App />
+</CartProvider>
+```
+
+---
+
+## 🌍 CDN Quick Demo
+
+```html
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>Cart Demo</title>
+	</head>
+	<body>
+		<script src="https://cdn.jsdelivr.net/npm/@ravishranjan/cart/dist/cart.min.js"></script>
+		<script>
+			const cart = new Cart();
+			cart.addItem({ id: 1, name: "Coffee", price: 120 });
+			console.log(cart.getTotal()); // 120
+		</script>
+	</body>
+</html>
+```
+
+---
+
+## 🧱 API Summary
+
+| API            | Type            | Description                     |
+| -------------- | --------------- | ------------------------------- |
+| `Cart`         | Class           | Core cart logic                 |
+| `CartProvider` | React Component | Context provider for cart state |
+| `useCart()`    | React Hook      | Access cart in React components |
+
+---
+
+## 🧾 License
+
+ISC © [Ravish Ranjan](https://npmjs.com/~ravishranjan)

package/dist/cart.min.js

@@ -0,0 +1 @@
+"use strict";var Cart=(()=>{var s=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var l=(i,t)=>{for(var e in t)s(i,e,{get:t[e],enumerable:!0})},y=(i,t,e,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of c(t))!u.call(i,a)&&a!==e&&s(i,a,{get:()=>t[a],enumerable:!(r=g(t,a))||r.enumerable});return i};var d=i=>y(s({},"__esModule",{value:!0}),i);var h={};l(h,{Cart:()=>o});function n(i){if(typeof window>"u")throw new Error("No window object found");return i=="localStorage"?window.localStorage:window.sessionStorage}var o=class{constructor({storage:t="localStorage",key:e="cart"}={}){this.storage=n(t),this.key=e}getCart(){let t=this.storage.getItem(this.key);return t?JSON.parse(t):[]}save(t){this.storage.setItem(this.key,JSON.stringify(t))}addItem(t){let e=this.getCart(),r=e.find(a=>a.id===t.id);r?r.quantity=(r.quantity||1)+(t.quantity||1):e.push({...t,quantity:t.quantity||1}),this.save(e)}removeItem(t){this.save(this.getCart().filter(e=>e.id!==t))}clear(){this.save([])}getItems(t){let e=this.getCart();return t?e.filter(r=>r.category===t):e}getTotal(t){let e=this.getCart();return t&&(e=e.filter(r=>r.category===t)),e.reduce((r,a)=>r+(a.price||0)*(a.quantity||1),0)}};return d(h);})();

package/dist/{chunk-K3ENNZKF.mjs → chunk-SR5T5KWM.mjs}

@@ -1,6 +1,6 @@
 import {
   CartContext
-} from "./chunk-3AB6KTDB.mjs";
+} from "./chunk-XPRNR6EK.mjs";
 
 // src/react/useCart.tsx
 import { useContext } from "react";

package/dist/{chunk-YTW5MCYO.mjs → chunk-TVKKRH3O.mjs}

@@ -18,12 +18,12 @@ var Cart = class {
   save(cart) {
     this.storage.setItem(this.key, JSON.stringify(cart));
   }
-  addItem(item) {
+  addItem(newItem) {
     const cart = this.getCart();
-    const exists = cart.find((item2) => item2.id === item2.id);
+    const exists = cart.find((item) => item.id === newItem.id);
     if (exists)
-      exists.quantity = (exists.quantity || 1) + (item.quantity || 1);
-    else cart.push({ ...item, quantity: item.quantity || 1 });
+      exists.quantity = (exists.quantity || 1) + (newItem.quantity || 1);
+    else cart.push({ ...newItem, quantity: newItem.quantity || 1 });
     this.save(cart);
   }
   removeItem(id) {

package/dist/{chunk-3AB6KTDB.mjs → chunk-XPRNR6EK.mjs}

@@ -1,13 +1,17 @@
 import {
   Cart
-} from "./chunk-YTW5MCYO.mjs";
+} from "./chunk-TVKKRH3O.mjs";
 
 // src/react/CartContext.tsx
 import { createContext, useEffect, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 var CartContext = createContext(null);
-var CartProvider = ({ children }) => {
-  const cartInstance = new Cart();
+var CartProvider = ({
+  children,
+  storage = "localStorage",
+  key = "cart"
+}) => {
+  const cartInstance = new Cart({ key, storage });
   const [items, setItems] = useState(cartInstance.getItems());
   const sync = () => setItems(cartInstance.getItems());
   const api = {

package/dist/core/cart.d.mts

@@ -15,7 +15,7 @@ declare class Cart {
     });
     private getCart;
     private save;
-    addItem(item: CartItem): void;
+    addItem(newItem: CartItem): void;
     removeItem(id: string | number): void;
     clear(): void;
     getItems(category?: string): CartItem[];

package/dist/core/cart.d.ts

@@ -15,7 +15,7 @@ declare class Cart {
     });
     private getCart;
     private save;
-    addItem(item: CartItem): void;
+    addItem(newItem: CartItem): void;
     removeItem(id: string | number): void;
     clear(): void;
     getItems(category?: string): CartItem[];

package/dist/core/cart.js

@@ -46,12 +46,12 @@ var Cart = class {
   save(cart) {
     this.storage.setItem(this.key, JSON.stringify(cart));
   }
-  addItem(item) {
+  addItem(newItem) {
     const cart = this.getCart();
-    const exists = cart.find((item2) => item2.id === item2.id);
+    const exists = cart.find((item) => item.id === newItem.id);
     if (exists)
-      exists.quantity = (exists.quantity || 1) + (item.quantity || 1);
-    else cart.push({ ...item, quantity: item.quantity || 1 });
+      exists.quantity = (exists.quantity || 1) + (newItem.quantity || 1);
+    else cart.push({ ...newItem, quantity: newItem.quantity || 1 });
     this.save(cart);
   }
   removeItem(id) {

package/dist/core/cart.mjs

@@ -1,6 +1,6 @@
 import {
   Cart
-} from "../chunk-YTW5MCYO.mjs";
+} from "../chunk-TVKKRH3O.mjs";
 import "../chunk-7RBGBF5M.mjs";
 export {
   Cart

package/dist/index.js

@@ -47,12 +47,12 @@ var Cart = class {
   save(cart) {
     this.storage.setItem(this.key, JSON.stringify(cart));
   }
-  addItem(item) {
+  addItem(newItem) {
     const cart = this.getCart();
-    const exists = cart.find((item2) => item2.id === item2.id);
+    const exists = cart.find((item) => item.id === newItem.id);
     if (exists)
-      exists.quantity = (exists.quantity || 1) + (item.quantity || 1);
-    else cart.push({ ...item, quantity: item.quantity || 1 });
+      exists.quantity = (exists.quantity || 1) + (newItem.quantity || 1);
+    else cart.push({ ...newItem, quantity: newItem.quantity || 1 });
     this.save(cart);
   }
   removeItem(id) {

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   Cart
-} from "./chunk-YTW5MCYO.mjs";
+} from "./chunk-TVKKRH3O.mjs";
 import {
   getStorage
 } from "./chunk-7RBGBF5M.mjs";

package/dist/react/CartContext.d.mts

@@ -10,8 +10,10 @@ type CartContextType = {
     total: number;
 };
 declare const CartContext: react.Context<CartContextType | null>;
-declare const CartProvider: ({ children }: {
+declare const CartProvider: ({ children, storage, key, }: {
     children: React.ReactNode;
+    storage?: "localStorage" | "sessionStorage";
+    key?: string;
 }) => react_jsx_runtime.JSX.Element;
 
 export { CartContext, type CartContextType, CartProvider };

package/dist/react/CartContext.d.ts

@@ -10,8 +10,10 @@ type CartContextType = {
     total: number;
 };
 declare const CartContext: react.Context<CartContextType | null>;
-declare const CartProvider: ({ children }: {
+declare const CartProvider: ({ children, storage, key, }: {
     children: React.ReactNode;
+    storage?: "localStorage" | "sessionStorage";
+    key?: string;
 }) => react_jsx_runtime.JSX.Element;
 
 export { CartContext, type CartContextType, CartProvider };

package/dist/react/CartContext.js

@@ -48,12 +48,12 @@ var Cart = class {
   save(cart) {
     this.storage.setItem(this.key, JSON.stringify(cart));
   }
-  addItem(item) {
+  addItem(newItem) {
     const cart = this.getCart();
-    const exists = cart.find((item2) => item2.id === item2.id);
+    const exists = cart.find((item) => item.id === newItem.id);
     if (exists)
-      exists.quantity = (exists.quantity || 1) + (item.quantity || 1);
-    else cart.push({ ...item, quantity: item.quantity || 1 });
+      exists.quantity = (exists.quantity || 1) + (newItem.quantity || 1);
+    else cart.push({ ...newItem, quantity: newItem.quantity || 1 });
     this.save(cart);
   }
   removeItem(id) {
@@ -81,8 +81,12 @@ var Cart = class {
 // src/react/CartContext.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var CartContext = (0, import_react.createContext)(null);
-var CartProvider = ({ children }) => {
-  const cartInstance = new Cart();
+var CartProvider = ({
+  children,
+  storage = "localStorage",
+  key = "cart"
+}) => {
+  const cartInstance = new Cart({ key, storage });
   const [items, setItems] = (0, import_react.useState)(cartInstance.getItems());
   const sync = () => setItems(cartInstance.getItems());
   const api = {

package/dist/react/CartContext.mjs

@@ -1,8 +1,8 @@
 import {
   CartContext,
   CartProvider
-} from "../chunk-3AB6KTDB.mjs";
-import "../chunk-YTW5MCYO.mjs";
+} from "../chunk-XPRNR6EK.mjs";
+import "../chunk-TVKKRH3O.mjs";
 import "../chunk-7RBGBF5M.mjs";
 export {
   CartContext,

package/dist/react/index.js

@@ -53,12 +53,12 @@ var Cart = class {
   save(cart) {
     this.storage.setItem(this.key, JSON.stringify(cart));
   }
-  addItem(item) {
+  addItem(newItem) {
     const cart = this.getCart();
-    const exists = cart.find((item2) => item2.id === item2.id);
+    const exists = cart.find((item) => item.id === newItem.id);
     if (exists)
-      exists.quantity = (exists.quantity || 1) + (item.quantity || 1);
-    else cart.push({ ...item, quantity: item.quantity || 1 });
+      exists.quantity = (exists.quantity || 1) + (newItem.quantity || 1);
+    else cart.push({ ...newItem, quantity: newItem.quantity || 1 });
     this.save(cart);
   }
   removeItem(id) {
@@ -86,8 +86,12 @@ var Cart = class {
 // src/react/CartContext.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var CartContext = (0, import_react.createContext)(null);
-var CartProvider = ({ children }) => {
-  const cartInstance = new Cart();
+var CartProvider = ({
+  children,
+  storage = "localStorage",
+  key = "cart"
+}) => {
+  const cartInstance = new Cart({ key, storage });
   const [items, setItems] = (0, import_react.useState)(cartInstance.getItems());
   const sync = () => setItems(cartInstance.getItems());
   const api = {

package/dist/react/index.mjs

@@ -1,10 +1,10 @@
 import {
   useCart
-} from "../chunk-K3ENNZKF.mjs";
+} from "../chunk-SR5T5KWM.mjs";
 import {
   CartProvider
-} from "../chunk-3AB6KTDB.mjs";
-import "../chunk-YTW5MCYO.mjs";
+} from "../chunk-XPRNR6EK.mjs";
+import "../chunk-TVKKRH3O.mjs";
 import "../chunk-7RBGBF5M.mjs";
 export {
   CartProvider,

package/dist/react/useCart.mjs

@@ -1,8 +1,8 @@
 import {
   useCart
-} from "../chunk-K3ENNZKF.mjs";
-import "../chunk-3AB6KTDB.mjs";
-import "../chunk-YTW5MCYO.mjs";
+} from "../chunk-SR5T5KWM.mjs";
+import "../chunk-XPRNR6EK.mjs";
+import "../chunk-TVKKRH3O.mjs";
 import "../chunk-7RBGBF5M.mjs";
 export {
   useCart

package/package.json

@@ -1,56 +1,62 @@
-{
-	"name": "@ravishranjan/cart",
-	"version": "2.0.8",
-	"description": "A native cart system for web apps with optional React hooks",
-	"main": "dist/index.js",
-	"module": "dist/index.mjs",
-	"types": "dist/types.d.ts",
-	"files": [
-		"dist"
-	],
-	"scripts": {
-		"build": "tsup src --format esm,cjs --dts",
-		"dev": "tsup src --watch"
-	},
-	"keywords": [
-		"cart",
-		"react",
-		"localstorage",
-		"frontend",
-		"native"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.mjs",
-			"require": "./dist/index.js"
-		},
-		"./react": {
-			"types": "./dist/react/index.d.ts",
-			"import": "./dist/react/index.mjs",
-			"require": "./dist/react/index.js"
-		}
-	},
-	"author": "Ravish Ranjan",
-	"license": "ISC",
-	"devDependencies": {
-		"@types/react": "^19.2.2",
-		"tsup": "^8.5.0",
-		"typescript": "^5.9.3"
-	},
-	"peerDependencies": {
-		"react": "^18.0.0 || ^19.0.0",
-		"react-dom": "^18.0.0 || ^19.0.0"
-	},
-	"peerDependenciesMeta": {
-		"react": {
-			"optional": true
-		},
-		"react-dom": {
-			"optional": true
-		},
-		"typescript": {
-			"optional": true
-		}
-	}
-}
+{
+	"name": "@ravishranjan/cart",
+	"version": "2.1.0",
+	"description": "A native cart system for web apps with optional React hooks",
+	"main": "dist/index.js",
+	"module": "dist/index.mjs",
+	"types": "dist/types.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup src --format esm,cjs --dts",
+		"dev": "tsup src --watch",
+		"build:cdn": "esbuild src/core/cart.ts --bundle --minify --format=iife --global-name=Cart --outfile=dist/cart.min.js",
+		"prepare": "npm run build && npm run build:cdn"
+	},
+	"keywords": [
+		"cart",
+		"react",
+		"localstorage",
+		"frontend",
+		"native",
+		"cdn"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.js"
+		},
+		"./react": {
+			"types": "./dist/react/index.d.ts",
+			"import": "./dist/react/index.mjs",
+			"require": "./dist/react/index.js"
+		}
+	},
+	"unpkg": "dist/cart.min.js",
+	"jsdelivr": "dist/cart.min.js",
+	"author": "Ravish Ranjan",
+	"license": "ISC",
+	"devDependencies": {
+		"@types/react": "^19.2.2",
+		"esbuild": "^0.25.10",
+		"tsup": "^8.5.0",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0",
+		"react-dom": "^18.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		},
+		"typescript": {
+			"optional": true
+		}
+	}
+}