Fluxion

"One API to control all data."

Fluxion is a full data orchestration engine that replaces Axios, React Query, SWR, and basic API SDKs with a single, unified API.

Features

• Zero-Config Defaults - Works out of the box, no configuration required
• HTTP Client - Full-featured replacement for Axios with interceptors, retry logic, and timeout support
• Request Deduplication - Automatically prevents duplicate requests
• Query Management - Powerful caching, deduplication, and automatic refetching (React Query/SWR alternative)
• Mutations - Optimistic updates and automatic cache invalidation
• Infinite Queries - Cursor-based and offset-based pagination made easy
• Plugin Ecosystem - Extensible with built-in plugins for logging, auth, rate limiting
• TypeScript First - Full type safety out of the box
• Cross-Platform - Works in Browser, Node.js, and Edge environments

Installation

npm install fluxion

Quick Start

Zero-Config Usage

import { createClient } from 'fluxion';

// Works immediately without configuration
const client = createClient();
const response = await client.get('https://api.example.com/users');

HTTP Client with Options

import { createClient } from 'fluxion';

const client = createClient({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  retry: 3,
  headers: {
    'Authorization': 'Bearer token',
  },
});

const response = await client.get('/users');
const users = await client.post('/users', { name: 'John' });

With React

import { FluxionProvider, useQuery, useMutation } from 'fluxion';
import { createClient } from 'fluxion';

const client = createClient({ baseURL: '/api' });

function App() {
  return (
    <FluxionProvider config={{ client }}>
      <UserList />
    </FluxionProvider>
  );
}

function UserList() {
  const { data, isLoading, refetch } = useQuery({
    queryKey: 'users',
    queryFn: () => client.get('/users').then(r => r.data),
  });

  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      {data?.map(user => <div key={user.id}>{user.name}</div>)}
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

function CreateUser() {
  const { mutate } = useMutation({
    mutationFn: (data) => client.post('/users', data).then(r => r.data),
    onSuccess: () => {
      // Cache automatically invalidated
    },
  });

  return <button onClick={() => mutate({ name: 'New User' })}>Add User</button>;
}

Infinite Queries (Pagination)

const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
  queryKey: ['posts'],
  queryFn: ({ pageParam = 0 }) => 
    client.get(`/posts?page=${pageParam}`).then(r => r.data),
  getNextPageParam: (lastPage) => lastPage.nextPage ?? undefined,
});

Using Plugins

import { createClient, loggingPlugin, authPlugin, rateLimitPlugin } from 'fluxion';

const client = createClient({ baseURL: '/api' });

client.plugins.use(loggingPlugin());
client.plugins.use(authPlugin({ token: 'your-token' }));
client.plugins.use(rateLimitPlugin({ maxRequests: 10, windowMs: 1000 }));

// Custom plugins
client.plugins.use({
  name: 'my-plugin',
  onRequest: (config) => {
    console.log('Request:', config.url);
    return config;
  },
  onResponse: (response) => {
    console.log('Response:', response.status);
    return response;
  },
});

API Reference

Client Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseURL | string | - | Base URL for all requests | | timeout | number | - | Request timeout in ms | | headers | Record<string, string> | {} | Default headers | | retry | number | 3 | Retry attempts | | retryDelay | (attempt) => number | exponential | Delay between retries | | deduplicate | boolean | true | Prevent duplicate requests | | fetch | typeof fetch | globalThis.fetch | Custom fetch implementation | | onRequest | (config) => config | - | Request interceptor | | onResponse | (response) => response | - | Response interceptor | | onError | (error) => error | - | Error interceptor |

Query Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | queryKey | string \| string[] \| object | Required | Unique query key | | queryFn | () => Promise<T> | Required | Data fetching function | | enabled | boolean | true | Enable/disable query | | staleTime | number | 0 | Cache duration (ms) | | cacheTime | number | 300000 | GC time | | refetchOnWindowFocus | boolean | true | Refetch on focus | | retry | number \| false | 3 | Retry attempts |

Built-in Plugins

• loggingPlugin() - Logs requests/responses/errors
• authPlugin({ token }) - Adds authentication headers
• rateLimitPlugin({ maxRequests, windowMs }) - Rate limiting

License

MIT