@catalystlabs/fluxstate

Real-time Reactive State Persistence Engine with Time-Travel Debugging

Features

• 🚀 Real-time Sync - Automatic synchronization across all connected clients
• 💾 Auto Persistence - Seamless Redis/Dragonfly integration
• 🔐 End-to-End Encryption - Military-grade encryption for sensitive data
• 🕐 Time-Travel Debugging - Step through state changes with DevTools
• 🎯 Perfect TypeScript - 100% type inference, no annotations needed
• ⚛️ Framework Support - React, Vue, and Svelte adapters included
• 📊 GraphQL-like Queries - Powerful reactive query system
• 🔄 Offline Support - Automatic sync when connection restored
• 🎨 DevTools Extension - Browser extension for debugging

Quick Start

npm install @catalystlabs/fluxstate

Basic Usage

import { createFluxState } from '@catalystlabs/fluxstate';

// Create a fully-featured state instance
const state = await createFluxState({
  namespace: 'myapp',
  initialState: {
    user: { name: '', email: '' },
    todos: []
  },
  redis: { 
    url: 'redis://localhost:6379' 
  },
  encryption: { 
    enabled: true 
  },
  devTools: true
});

// Use with perfect TypeScript inference
state.user.name = 'John Doe'; // ✅ Fully typed!
state.todos.push({ id: 1, text: 'Build app', done: false });

// Subscribe to changes
state.$subscribe('user.name', (newName) => {
  console.log('Name changed:', newName);
});

React Integration

import { useFluxState } from '@catalystlabs/fluxstate/react';

function UserProfile() {
  const user = useFluxState((state) => state.user);
  
  return (
    <div>
      <h1>{user.name}</h1>
      <input 
        value={user.email}
        onChange={(e) => user.email = e.target.value}
      />
    </div>
  );
}

Vue Integration

<template>
  <div>
    <h1>{{ user.name }}</h1>
    <input v-model="user.email" />
  </div>
</template>

<script setup>
import { useFluxState } from '@catalystlabs/fluxstate/vue';

const user = useFluxState((state) => state.user);
</script>

Svelte Integration

<script>
import { fluxState } from '@catalystlabs/fluxstate/svelte';

const user = fluxState('user');
</script>

<h1>{$user.name}</h1>
<input bind:value={$user.email} />

Advanced Features

Time-Travel Debugging

// Enable DevTools
const state = await createFluxState({
  devTools: true
});

// Use time-travel
state.$devTools.timeTravel.undo();
state.$devTools.timeTravel.redo();
state.$devTools.timeTravel.jumpToSnapshot(5);

Encrypted Fields

// Mark fields as encrypted
const state = await createFluxState({
  initialState: {
    public: { name: 'John' },
    $secure: { 
      ssn: '', 
      creditCard: '' 
    }
  },
  encryption: { enabled: true }
});

// Automatically encrypted/decrypted
state.$secure.ssn = '123-45-6789';

Reactive Queries

// Create reactive queries
const activeUsers = state.$query({
  collection: 'users',
  filter: { active: true },
  sort: [{ field: 'name', order: 'asc' }]
});

// Auto-updates when data changes
activeUsers.subscribe(users => {
  console.log('Active users:', users);
});

Multi-Tenant Support

const state = await createFluxState({
  redis: {
    url: 'redis://localhost:6379',
    tenantIsolation: 'namespace'
  }
});

// Isolated tenant data
const tenant1 = await state.$tenant('customer-1');
const tenant2 = await state.$tenant('customer-2');

Architecture

FluxState is built as a layered architecture:

• Layer 0: Redis/Dragonfly connection management (Rust)
• Layer 1: Key-Value operations with compression (Rust)
• Layer 1.5: Encryption layer with WASM module (Rust/WASM)
• Layer 1.75: Backup and restore functionality
• Layer 2: Real-time synchronization with CRDT
• Layer 2.5: Reactive query engine
• Layer 3: Core reactive store
• Layer 4: Persistence rules and middleware
• Layer 5: TypeScript type magic
• Layer 6: Framework adapters
• Layer 7: Developer tools

Configuration

const state = await createFluxState({
  // Required
  namespace: 'myapp',
  
  // Optional
  initialState: {},
  
  // Redis configuration
  redis: {
    url: 'redis://localhost:6379',
    password: 'optional-password',
    tenantIsolation: 'none' | 'namespace' | 'database' | 'cluster'
  },
  
  // Encryption options
  encryption: {
    enabled: true,
    masterKey: 'optional-master-key', // Auto-generated if not provided
    algorithm: 'aes-256-gcm' | 'chacha20-poly1305'
  },
  
  // Sync options
  sync: {
    transport: 'websocket' | 'sse' | 'webrtc' | 'hybrid',
    url: 'wss://sync.example.com',
    reconnect: true,
    reconnectDelay: 1000
  },
  
  // Performance options
  performance: {
    debounceMs: 100,
    batchUpdates: true,
    compression: 'lz4' | 'zstd' | 'none'
  },
  
  // Development
  devTools: true
});

Performance

FluxState is designed for high performance:

• Sub-10ms state updates
• Automatic batching of Redis operations
• LZ4/Zstd compression for large objects
• Efficient CRDT-based conflict resolution
• Smart caching with reactive invalidation

Browser Support

• Chrome/Edge 80+
• Firefox 75+
• Safari 13+
• Opera 67+

Contributing

See CONTRIBUTING.md

License

MIT © FluxState Team