npm package: @catalystlabs/fluxstate
Description: Real-time Reactive State Persistence Engine with Time-Travel Debugging
Author: FluxState Team
Latest version: 0.0.1

# @catalystlabs/fluxstate

[![npm version](https://img.shields.io/npm/v/@catalystlabs/fluxstate.svg)](https://www.npmjs.com/package/@catalystlabs/fluxstate)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
npm install @catalystlabs/fluxstate
```

### Basic Usage

```typescript
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

```tsx
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

```vue
<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

```svelte
<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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
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

```typescript
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](https://github.com/fluxstate/fluxstate/blob/main/CONTRIBUTING.md)

## License

MIT © FluxState Team