swr-resource 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prabhat Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# ⚡ swr-resource
+
+A zero-boilerplate, modern resource wrapper around **SWR** for lightning-fast React data fetching and CRUD operations.
+
+Built for enterprise-scale applications, **swr-resource** eliminates repetitive API calls, loading state management, and manual cache updates. It keeps your UI synchronized automatically.
+
+---
+
+## ✨ Features
+
+- 🚀 **Zero Boilerplate** – Perform complete CRUD operations with a single hook.
+- 🔄 **Automatic Cache Sync** – UI updates automatically after `create`, `update`, and `remove` operations.
+- 🔐 **Global Configuration** – Configure your API base URL and authentication token once.
+- 📦 **Lightweight** – Built on top of the powerful `swr` library.
+- 💙 **TypeScript Ready** – Fully typed for an excellent developer experience.
+- ⚡ **Optimized Performance** – Leverages SWR's caching and revalidation features.
+
+---
+
+# 📦 Installation
+
+Install **swr-resource** along with its peer dependency, **SWR**.
+
+```bash
+npm install swr-resource swr
+```
+
+or
+
+```bash
+yarn add swr-resource swr
+```
+
+or
+
+```bash
+pnpm add swr-resource swr
+```
+
+---
+
+# 🛠️ Setup
+
+Wrap your application with the `ApiProvider`.
+
+This allows you to configure a global API base URL and automatically inject authentication tokens into every request.
+
+```tsx
+// App.tsx
+import React from "react";
+import { ApiProvider } from "swr-resource";
+import Dashboard from "./Dashboard";
+
+export default function App() {
+  return (
+    <ApiProvider
+      baseURL="https://api.yourdomain.com/v1"
+      getAuthToken={() => localStorage.getItem("access_token")}
+    >
+      <Dashboard />
+    </ApiProvider>
+  );
+}
+```
+
+---
+
+# 💻 Usage
+
+Once the provider is configured, use the `useResource` hook anywhere in your application.
+
+```tsx
+import React, { useState } from "react";
+import { useResource } from "swr-resource";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+export default function UserManagement() {
+  const {
+    data: users,
+    isLoading,
+    error,
+    create,
+    remove,
+  } = useResource<User[]>("/users");
+
+  const [newName, setNewName] = useState("");
+
+  if (isLoading) return <p>Loading users...</p>;
+
+  if (error) return <p>Failed to load users.</p>;
+
+  const handleAddUser = async () => {
+    await create({
+      name: newName,
+      email: "new@example.com",
+    });
+
+    setNewName("");
+  };
+
+  return (
+    <div>
+      <h2>User Management</h2>
+
+      <div>
+        <input
+          value={newName}
+          onChange={(e) => setNewName(e.target.value)}
+          placeholder="Enter user name"
+        />
+
+        <button onClick={handleAddUser}>
+          Add User
+        </button>
+      </div>
+
+      <ul>
+        {users?.map((user) => (
+          <li key={user.id}>
+            {user.name} ({user.email})
+
+            <button
+              onClick={() => remove(user.id)}
+            >
+              Delete
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+# 📚 API Reference
+
+## `<ApiProvider />`
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `baseURL` | `string` | Base URL of your API (e.g. `https://api.example.com`) |
+| `getAuthToken` | `() => string \| null` | Function that returns the current Bearer token. It is evaluated before every request. |
+
+---
+
+## `useResource(endpoint)`
+
+Returns the following object:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `T` | Fetched resource data |
+| `isLoading` | `boolean` | `true` while the initial request is loading |
+| `isValidating` | `boolean` | `true` whenever SWR is revalidating |
+| `error` | `Error` | Error object if the request fails |
+| `create(payload)` | `Promise<any>` | Sends a `POST` request and automatically revalidates the cache |
+| `update(id, payload)` | `Promise<any>` | Sends a `PUT` request to `endpoint/:id` and revalidates |
+| `remove(id)` | `Promise<any>` | Sends a `DELETE` request to `endpoint/:id` and revalidates |
+| `refresh()` | `() => void` | Manually re-fetches the current resource |
+
+---
+
+# Example
+
+```tsx
+const {
+  data,
+  create,
+  update,
+  remove,
+  refresh,
+} = useResource("/products");
+```
+
+---
+
+# Why swr-resource?
+
+Instead of writing this:
+
+```tsx
+const { data, mutate } = useSWR("/users");
+
+await axios.post("/users", payload);
+
+mutate();
+```
+
+Simply write:
+
+```tsx
+const { data, create } = useResource("/users");
+
+await create(payload);
+```
+
+No manual cache updates.
+
+No repetitive Axios calls.
+
+Just clean, declarative CRUD.
+
+---
+
+# Requirements
+
+- React 18+
+- SWR 2+
+- TypeScript (optional but recommended)
+
+---
+
+# License
+
+MIT