🔮 Lucent-Flow

Lucent-Flow is a lightweight, blazing-fast state management and data-fetching library for React and TypeScript. Designed to be tiny, reactive, and composable — with middleware support like logging and persistence baked in.

---

✨ Features

• 🔄 Minimal global state management with React hooks
• ⚙️ Custom middleware support (logging, persistence, etc.)
• 🧠 Typesafe with full TypeScript support
• 💾 AsyncStorage/localStorage persistence
• 📦 Lightweight and tree-shakable
• 🔌 Ready for server-side or native apps

---

📦 Installation

1npm install lucent-flow

Quick Start

1// Import core functionality
2import { createStore } from "lucent-flow";
3
4// Import middleware
5import { logger, devtools } from "lucent-flow";
6
7// Create a store with middleware
8const useStore = createStore(
9  (set) => ({
10    count: 0,
11    increment: () => set((state) => ({ count: state.count + 1 })),
12  }),
13  [logger(), devtools()]
14);
15
16// Use in your components
17function Counter() {
18  const { count, increment } = useStore();
19  return <button onClick={increment}>Count: {count}</button>;
20}

Core Features

• State Management: Create stores with type-safe state and actions
• Middleware Support: Built-in middleware for logging, devtools, and more
• TypeScript First: Full type safety out of the box

Documentation

See our documentation for detailed guides on:

• State Management
• Middleware
• API Reference

📡 LucentQuery - Data Fetching Made Simple

LucentQuery provides a powerful and flexible way to handle data fetching with built-in caching, retries, and optimistic updates.

Basic Usage

1// Import LucentQuery
2import { lucentQuery, QueryBuilder } from "lucent-flow";
3
4// 1. Create a base query instance
5const api = lucentQuery({
6  baseUrl: "https://api.example.com",
7  // Optional: Add default headers
8  headers: {
9    "Content-Type": "application/json",
10  },
11});
12
13// 2. Use in your store
14const usePostStore = createStore((set) => ({
15  posts: [],
16  loading: false,
17  error: null,
18
19  fetchPosts: async () => {
20    set({ loading: true });
21    try {
22      const result = await api({
23        url: "/posts",
24        method: "GET",
25      });
26      set({ posts: result.data, loading: false });
27    } catch (error) {
28      set({ error, loading: false });
29    }
30  },
31}));

Advanced Usage with QueryBuilder

1// 1. Create a QueryBuilder instance
2const queryBuilder = new QueryBuilder("https://api.example.com");
3
4// 2. Build complex queries
5const fetchPosts = async (filters) => {
6  const query = queryBuilder
7    .from("posts")
8    .where("status", "published")
9    .sort("createdAt", "desc")
10    .paginate(1, 10)
11    .include("author")
12    .build();
13
14  return await api(query);
15};
16
17// 3. Use in your component
18function PostList() {
19  const { posts, fetchPosts } = usePostStore();
20
21  useEffect(() => {
22    fetchPosts({ status: "published" });
23  }, []);
24
25  return (
26    <div>
27      {posts.map((post) => (
28        <div key={post.id}>{post.title}</div>
29      ))}
30    </div>
31  );
32}

Features

• Automatic Caching: Built-in cache management with configurable TTL
• Optimistic Updates: Update UI before server response
• Request Deduplication: Prevent duplicate requests
• Retry Logic: Automatic retries for failed requests
• Type Safety: Full TypeScript support
• Query Builder: Chainable API for complex queries

Configuration Options

1const api = lucentQuery({
2  baseUrl: "https://api.example.com",
3  // Cache configuration
4  cache: {
5    ttl: 5 * 60 * 1000, // 5 minutes
6    maxSize: 100,
7  },
8  // Retry configuration
9  retry: {
10    maxAttempts: 3,
11    delay: 1000,
12  },
13  // Request interceptors
14  requestInterceptors: [
15    async (config) => {
16      // Add auth token
17      config.headers.Authorization = `Bearer ${token}`;
18      return config;
19    },
20  ],
21  // Response interceptors
22  responseInterceptors: [
23    async (response) => {
24      // Handle response
25      return response;
26    },
27  ],
28});

For more details, see our API Documentation and Query Guide.