Types API

TypeScript type definitions for the flag store.

Core Types

FlagValue

Valid types for flag values.

type FlagValue = boolean | number | string

Only these three types can be stored in the flag store. Objects, arrays, null, and undefined are not valid stored values.

FlagStore

Main interface for a flag store.

interface FlagStore {
  // Reading
  get(key: string): FlagValue | undefined
  has(key: string): boolean
  all(): Record<string, FlagValue>
  keys(): string[]

  // Writing
  set(key: string, value: FlagValue | null | undefined): FlagStore
  delete(key: string): FlagStore
  clear(): FlagStore
  setMany(values: Record<string, FlagValue | null | undefined>): FlagStore

  // Specialized writes
  toggle(key: string): boolean
  increment(key: string, amount?: number): number
  decrement(key: string, amount?: number): number

  // Queries
  check(condition: string): boolean

  // Subscriptions
  subscribe(callback: ChangeCallback): UnsubscribeFn
  subscribeKey(key: string, callback: KeyChangeCallback): UnsubscribeFn

  // Organization
  namespace(prefix: string): FlagStore
  batch<T>(fn: () => T): T
  compute(key: string, dependencies: string[], fn: ComputeFn): void
}

FlagStoreWithHistory

Extended store with undo/redo support.

interface FlagStoreWithHistory extends FlagStore {
  undo(): boolean
  redo(): boolean
  canUndo(): boolean
  canRedo(): boolean
  clearHistory(): void
}

Returned when store is created with history: true.

FlagStoreWithPersistence

Extended store with persistence support.

interface FlagStoreWithPersistence extends FlagStore {
  save(): void
  load(): void
}

Returned when store is created with persist: { ... }.

Configuration Types

FlagStoreOptions

Options for createFlagStore().

interface FlagStoreOptions {
  initial?: Record<string, FlagValue>
  persist?: PersistOptions
  history?: boolean | HistoryOptions
}

PersistOptions

Options for persistent storage.

interface PersistOptions {
  storage: Storage
  key?: string
  autoSave?: boolean
}

HistoryOptions

Options for undo/redo history.

interface HistoryOptions {
  maxHistory?: number
}

Storage

Interface for storage backends.

interface Storage {
  getItem(key: string): string | null
  setItem(key: string, value: string): void
  removeItem(key: string): void
}

Compatible with localStorage and sessionStorage.

Callback Types

ChangeCallback

Callback for global subscriptions.

type ChangeCallback = (
  key: string,
  newValue: FlagValue | undefined,
  oldValue: FlagValue | undefined
) => void

KeyChangeCallback

Callback for key-specific subscriptions.

type KeyChangeCallback = (
  newValue: FlagValue | undefined,
  oldValue: FlagValue | undefined
) => void

UnsubscribeFn

Function to stop receiving notifications.

type UnsubscribeFn = () => void

Safe to call multiple times.

ComputeFn

Function for computing derived values.

type ComputeFn = (...values: Array<FlagValue | undefined>) => FlagValue

Receives dependency values in order, must return a FlagValue.

Type Casting

When using history or persistence, cast to access additional methods:

import {
  createFlagStore,
  FlagStoreWithHistory,
  FlagStoreWithPersistence
} from '@motioneffector/flags'

// History store
const historyStore = createFlagStore({
  history: true
}) as FlagStoreWithHistory

historyStore.undo()
historyStore.canRedo()

// Persistence store
const persistStore = createFlagStore({
  persist: { storage: localStorage }
}) as FlagStoreWithPersistence

persistStore.save()
persistStore.load()

// Both features
const fullStore = createFlagStore({
  history: true,
  persist: { storage: localStorage }
}) as FlagStoreWithHistory & FlagStoreWithPersistence

fullStore.undo()
fullStore.save()