@litforge/state-vue

Vue.js integration for @litforge/state. Provides a composable hook for using the state management system in Vue 3 applications.

Overview

@litforge/state-vue wraps @litforge/state with Vue-specific functionality, providing reactive state management through Vue's Composition API.

Installation

npm install @litforge/state-vue @litforge/state
# or
pnpm add @litforge/state-vue @litforge/state
# or
yarn add @litforge/state-vue @litforge/state

Note: @litforge/state is a peer dependency and must be installed separately.

Requirements

• Vue 3.x
• @litforge/state

Basic Usage

Using the Composable

<script setup lang="ts">
import { useStateSystem } from '@litforge/state-vue';

const { ready, log, pushEvent, subscribe, replay } = useStateSystem({
  connectDevtools: true,
  getState: () => window.__STATE__ ?? {},
  restoreState: (state) => {
    window.__STATE__ = state;
  }
});

// Push an event
const handleAction = () => {
  pushEvent({
    type: 'USER_ACTION',
    payload: { action: 'click' }
  });
};

// Subscribe to events
subscribe((event) => {
  console.log('Event received:', event);
});
</script>

<template>
  <div v-if="ready">
    <p>State system ready!</p>
    <button @click="handleAction">Trigger Event</button>
  </div>
</template>

API

useStateSystem(options?)

Returns a reactive object with the following properties:

Options

interface UseStateSystemOptions<TState = any> {
  connectDevtools?: boolean;  // Connect to Redux DevTools (default: true)
  getState?: () => TState;    // Function to get current state
  restoreState?: (state: TState) => void; // Function to restore state
}

Return Value

• ready: Computed ref indicating if the state system is initialized
• log: Computed ref to the ActionLog instance
• pushEvent(event): Function to push a new event
• subscribe(fn): Function to subscribe to events
• replay(index, applyEvent): Function to replay events
• export(): Export state as JSON string
• import(json): Import state from JSON string
• instance: Getter for the ActionLog instance

Example: Full Integration

<script setup lang="ts">
import { ref, computed } from 'vue';
import { useStateSystem } from '@litforge/state-vue';

// Your application state
const appState = ref({
  user: null,
  todos: []
});

// Initialize state system
const { ready, pushEvent, subscribe } = useStateSystem({
  connectDevtools: true,
  getState: () => appState.value,
  restoreState: (state) => {
    appState.value = state;
  }
});

// Subscribe to events and update state
subscribe((event) => {
  switch (event.type) {
    case 'USER_LOGIN':
      appState.value.user = event.payload;
      break;
    case 'ADD_TODO':
      appState.value.todos.push(event.payload);
      break;
  }
});

// Actions
const login = (user) => {
  pushEvent({
    type: 'USER_LOGIN',
    payload: user
  });
};

const addTodo = (todo) => {
  pushEvent({
    type: 'ADD_TODO',
    payload: todo
  });
};
</script>

Lifecycle

The composable automatically:

• Initializes the state system on component mount
• Cleans up subscriptions on component unmount
• Handles async initialization gracefully

TypeScript Support

Fully typed with TypeScript:

import { useStateSystem } from '@litforge/state-vue';
import type { UseStateSystemOptions } from '@litforge/state-vue';

interface MyState {
  user: { id: string; name: string };
  count: number;
}

const options: UseStateSystemOptions<MyState> = {
  getState: () => ({ user: { id: '1', name: 'John' }, count: 0 }),
  restoreState: (state) => { /* ... */ }
};

const { log } = useStateSystem<MyState>(options);

License

Part of the LitForge component library.