Core Concepts

Understanding the fundamental concepts of Storken state management.

State Management Philosophy

Storken follows a simple yet powerful philosophy: make state management as intuitive as using React's useState, but with the power of global state, async operations, and plugin extensibility.

Core Principles

1. Universal API

Same API pattern everywhere - whether you're managing local component state or global app state.

2. LLM-First Design

Predictable patterns that AI assistants can easily understand and generate code for.

3. Zero Boilerplate

No actions, reducers, or complex setup. Just create and use.

The Storken Pattern

Every Storken hook returns a consistent array pattern:

const [
  value,      // Current state value
  setValue,   // Setter function (supports callbacks)
  reset,      // Reset to initial value
  loading,    // Loading state for async operations
  update,     // Trigger getter/refetch
  plugins     // Plugin instances
] = useStorken('key', initialValue)

Pro tip: This pattern is identical to useState, just with more capabilities. You can destructure only what you need.

State Types

Simple State

Basic state values that work like useState:

const [count, setCount] = useStorken('count', 0)
const [user, setUser] = useStorken<User | null>('user', null)
const [theme, setTheme] = useStorken('theme', 'light')

Async State (Getters)

States that fetch data asynchronously:

const [useStorken] = create({
  getters: {
    user: async () => {
      const res = await fetch('/api/user')
      return res.json()
    }
  }
})

// Usage
const [user, , , loading, refetch] = useStorken('user')

Side Effect State (Setters)

States that trigger side effects when updated:

const [useStorken] = create({
  setters: {
    user: async (storken, newUser) => {
      await fetch('/api/user', {
        method: 'PUT',
        body: JSON.stringify(newUser)
      })
    }
  }
})

// Usage - automatically shows loading during update
const [user, setUser, , loading] = useStorken('user')

Sky Instance

The Sky instance provides direct, synchronous access to your store outside of React components:

const [useStorken, get, set, sky] = create({
  initialValues: { count: 0 }
})

// Use in event handlers, utilities, or anywhere
sky.get('count')           // Get value
sky.set('count', 10)       // Set value
sky.reset('count')         // Reset to initial
sky.subscribe('count', (value) => {  // Subscribe to changes
  console.log('Count changed:', value)
})

Plugin System

Extend Storken with custom plugins for persistence, logging, or any custom behavior:

const persistPlugin = (storken) => {
  // Load from localStorage on init
  const saved = localStorage.getItem(`storken_${storken.key}`)
  if (saved) storken.set(JSON.parse(saved))
  
  // Save to localStorage on change
  storken.on('set', (value) => {
    localStorage.setItem(`storken_${storken.key}`, JSON.stringify(value))
  })
  
  // Return plugin API
  return {
    clear: () => localStorage.removeItem(`storken_${storken.key}`)
  }
}

// Use the plugin
const [useStorken] = create({
  plugins: { persist: persistPlugin }
})

// Access plugin methods
const [value, , , , , plugins] = useStorken('key')
plugins.persist.clear() // Clear persisted data

Next Steps

Now that you understand the core concepts, explore: