Interface KeyValueModel

Key-Value Model - Persistent, reactive state storage with real-time synchronization across KOS applications.

This model provides a namespaced key-value store that automatically persists data and synchronizes changes across all connected clients in real-time. Perfect for storing user preferences, application state, feature flags, or any data that needs to persist between sessions and sync across instances.

Key Features

  • Persistent Storage - Data survives application restarts and browser refreshes
  • Real-time Synchronization - Changes propagate instantly to all connected clients
  • Namespace Isolation - Multiple stores can coexist without key collisions
  • Type-Safe Values - Supports string, number, boolean, and undefined types
  • Reactive Updates - Automatic UI updates when values change (locally or remotely)
  • Topic-Based Sync - Uses KOS event system for distributed state management

Topic-Based Reactivity

The model listens to two KOS topics for real-time synchronization:

  • /keyVal/set - Fired when any key-value pair is updated or added
  • /keyVal/remove - Fired when a key is deleted from the store

These topics ensure that all instances of the model with the same namespace stay synchronized across browser tabs, windows, and even different client applications. The model automatically filters events by namespace to ensure isolation.

Example: Basic Usage

const preferences = KeyValue.instance('user-prefs')
  .options({ namespace: 'preferences' })
  .build();

// Store values
await preferences.updateState('theme', 'dark');
await preferences.updateState('fontSize', 14);

// Access reactive data
console.log(preferences.data.theme);     // 'dark'
console.log(preferences.data.fontSize);  // 14

Example: React Integration

const UserSettings: React.FC = kosComponent(() => {
  const settings = useModel(KeyValue, 'app-settings');

  return (
    <div>
      <p>Theme: {settings.data.theme || 'light'}</p>
      <button onClick={() => settings.updateState('theme', 'dark')}>
        Set Dark Theme
      </button>
    </div>
  );
});

Use Declared Type

See

interface KeyValueModel {
    updateState(key, value): Promise<void>;
    handleStateUpdate(update): void;
    handleStateDelete(update): void;
}

Methods

updateState handleStateUpdate handleStateDelete

Methods

updateState

  • updateState(key, value): Promise<void>

  • Update or delete a key-value pair in the store.

    Changes are automatically persisted and synchronized across all instances with the same namespace via KOS topics.

    Parameters

    • key: string

      The key to update or delete

    • value: undefined | string | number | boolean

      The value to set (string | number | boolean), or undefined to delete the key

    Returns Promise<void>

    Promise that resolves when the operation completes

    Example

    // Set a value
    await keyValue.updateState('theme', 'dark');

    // Delete a key
    await keyValue.updateState('theme', undefined);

handleStateUpdate

  • handleStateUpdate(update): void

  • Topic handler for /keyVal/set events to sync updates across instances.

    Automatically called when any KeyValue model instance updates a value, ensuring all instances with the same namespace stay synchronized.

    Parameters

    • update: KeyValueUpdate

      The key-value update event containing namespace, key, and new value

    Returns void

handleStateDelete

  • handleStateDelete(update): void

  • Topic handler for /keyVal/remove events to sync deletions across instances.

    Automatically called when any KeyValue model instance deletes a key, ensuring all instances with the same namespace stay synchronized.

    Parameters

    • update: KeyValueUpdate

      The key-value update event containing namespace and deleted key

    Returns void

Settings

Member Visibility

Theme

On This Page

updateStatehandleStateUpdatehandleStateDelete