xsoulspace_state_utils

A Dart package providing ordered collections and reactive state management utilities for Flutter applications.

What it does

Solves two key problems:

  • Ordered collections: Maps and Lists that maintain insertion order with key-based access
  • Reactive state management: Notifiers for ordered collections that automatically notify listeners of changes

Installation

dependencies:
  xsoulspace_state_utils: ^0.1.0

Quick Start

import 'package:xsoulspace_state_utils/xsoulspace_state_utils.dart';

// Ordered map that maintains insertion order
final orderedMap = MutableOrderedMap<String, User>();
orderedMap.upsert('alice', User(name: 'Alice'));
orderedMap.upsert('bob', User(name: 'Bob'));

// Access by key or iterate in order
print(orderedMap['alice']); // User(name: 'Alice')
print(orderedMap.orderedValues); // [User(Alice), User(Bob)]

// Efficient batch operations
final users = [
  User(id: 'user1', name: 'Alice'),
  User(id: 'user2', name: 'Bob'),
  User(id: 'user3', name: 'Charlie'),
];

// Batch insert multiple users efficiently (single cache invalidation)
orderedMap.upsertAll(users);

// Reactive notifier for state management with efficient batch updates
final userNotifier = OrderedMapNotifier<String, User>();
userNotifier.addListener(() => print('Users changed'));

// Batch update with single notification (prevents excessive UI rebuilds)
userNotifier.upsertAll(users);

Core Components

Ordered Collections

  • MutableOrderedMap<K, V> - Ordered map with mutable operations
  • ImmutableOrderedMap<K, V> - Immutable ordered map
  • MutableOrderedList<V> - Ordered list with mutable operations
  • ImmutableOrderedList<V> - Immutable ordered list
  • MutableOrderedSet<V> - Ordered set with mutable operations
  • ImmutableOrderedSet<V> - Immutable ordered set

State Notifiers

  • OrderedMapNotifier<K, V> - Reactive ordered map notifier
  • OrderedListNotifier<V> - Reactive ordered list notifier

Both extend Flutter's ChangeNotifier for automatic UI updates.

Experimental

  • Chain<TStartWith, TThenResult> - Type-safe command pipeline pattern (may be removed)

Agentic Executable (AE) Usage Patterns:

TODO: migrate to Agentic Executable (AE).

Rules are in ai_use folder.

  • command_resource_pattern.mdc - Command-Resource Pattern

License

MIT License. See LICENSE for details.

Libraries

xsoulspace_state_utils