refactor: code quality overhaul, new APIs, tests, and docs

Code quality (entitygen.hpp):
- Replace component_entry std::pair with named struct (.key, .comp)
- Replace entity::to_string() loop with std::ranges::fold_left_first
- Add default_to_string support for long type
- Validate choice_component/weighted_choice_component constructors
  (throw std::invalid_argument on empty or all-zero weights)

New APIs:
- entity::size(), entity::empty()
- eg::clear(), eg::size(), eg::component_keys()
- operator<<(wostream, stats_observer)

Rename eg::count() → eg::size() for STL consistency with
entity::size(); count() in C++ idiom means "occurrences of X",
size() means "total number of elements".

Tests (254 cases, 746 assertions):
- ~35 new test cases: input validation, boundary conditions,
  error messages, edge cases, move semantics, observer ordering,
  async failure, stream operator, empty entity serialization
- Fix shallow stats assertions with deterministic retry counts
- Simplify clear_generator fixture to use eg::clear()

Docs:
- Document default_to_string supported types
- Document entity::get_any(), keys(), size(), empty()
- Document eg::clear(), size(), component_keys()
- Add behavior notes for add/remove/remove_group
- Add observer thread safety warning
- Fix stale roadmap references in README

Example:
- Add demos for validate(), entity inspection, multiple observers,
  weight overrides, independent instances, error handling, clear()

Author: dasmig

README.md

@@ -1,5 +1,7 @@
 # Entity Generator for C++
 
+> **Requires C++23** (e.g., `-std=c++23` for GCC/Clang, `/std:c++latest` for MSVC).
+
 [![Entity Generator for C++](https://raw.githubusercontent.com/dasmig/entity-generator/master/doc/entity-generator.png)](https://github.com/dasmig/entity-generator/releases)
 
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/dasmig/entity-generator/main/LICENSE)
@@ -103,4 +105,4 @@ auto seeded = eg::instance().generate(42);
 
 For the complete feature guide — component dependencies, custom types, seed signatures, batch generation, groups, weights, validation, event hooks, extensions, and more — see the **[Usage Guide](doc/usage.md)**.
 
-For planned features — concurrent generation, conditional components, structured serialization, EnTT integration, and more — see the **[Roadmap](doc/roadmap.md)**.
+For planned features — EnTT integration, Python/Node.js/.NET wrappers, and more — see the **[Roadmap](doc/roadmap.md)**.

dasmig/entitygen.hpp

@@ -10,6 +10,7 @@
 #include <iterator>
 #include <map>
 #include <memory>
+#include <optional>
 #include <ostream>
 #include <ranges>
 #include <span>
@@ -125,6 +126,10 @@ class component
         {
             return std::to_wstring(std::any_cast<float>(value));
         }
+        if (value.type() == typeid(long))
+        {
+            return std::to_wstring(std::any_cast<long>(value));
+        }
         if (value.type() == typeid(bool))
         {
             return std::any_cast<bool>(value) ? L"true" : L"false";
@@ -181,7 +186,11 @@ class choice_component : public component
     explicit choice_component(std::wstring key, std::vector<T> choices,
                               Formatter fmt = {})
         : _key{std::move(key)}, _choices{std::move(choices)},
-          _fmt{std::move(fmt)} {}
+          _fmt{std::move(fmt)}
+    {
+        if (_choices.empty())
+            throw std::invalid_argument("choices must not be empty");
+    }
 
     [[nodiscard]] std::wstring key() const override { return _key; }
 
@@ -296,7 +305,15 @@ class weighted_choice_component : public component
                                        std::vector<option> options,
                                        Formatter fmt = {})
         : _key{std::move(key)}, _options{std::move(options)},
-          _fmt{std::move(fmt)} {}
+          _fmt{std::move(fmt)}
+    {
+        if (_options.empty())
+            throw std::invalid_argument("options must not be empty");
+        if (!std::ranges::any_of(_options,
+                [](const auto& o) { return o.weight > 0.0; }))
+            throw std::invalid_argument(
+                "at least one option must have a positive weight");
+    }
 
     [[nodiscard]] std::wstring key() const override { return _key; }
 
@@ -395,23 +412,25 @@ class entity
         return result;
     }
 
+    // Number of component values in this entity.
+    [[nodiscard]] std::size_t size() const { return _entries.size(); }
+
+    // Check if the entity has no component values.
+    [[nodiscard]] bool empty() const { return _entries.empty(); }
+
     // Convert all component values to a single formatted string.
     // Each entry is rendered as "key: display" separated by "  ".
     [[nodiscard]] std::wstring to_string() const
     {
-        std::wstring result;
-
-        for (const auto& e : _entries)
-        {
-            if (!result.empty())
-            {
-                result += L"  ";
-            }
-
-            result += e.key + L": " + e.display;
-        }
+        auto parts = _entries
+            | std::views::transform([](const auto& e) {
+                return e.key + L": " + e.display;
+            });
 
-        return result;
+        return std::ranges::fold_left_first(parts,
+            [](std::wstring acc, const std::wstring& part) {
+                return std::move(acc) + L"  " + part;
+            }).value_or(std::wstring{});
     }
 
     // Operator ostream streaming all component values in generation order.
@@ -537,15 +556,15 @@ class eg
         const auto key = comp->key();
         notify(&generation_observer::on_before_add, key);
 
-        auto it = std::ranges::find(_components, key, &component_entry::first);
+        auto it = std::ranges::find(_components, key, &component_entry::key);
 
         if (it != _components.end())
         {
-            it->second = std::move(comp);
+            it->comp = std::move(comp);
         }
         else
         {
-            _components.emplace_back(key, std::move(comp));
+            _components.push_back({key, std::move(comp)});
         }
 
         notify(&generation_observer::on_after_add, key);
@@ -580,8 +599,8 @@ class eg
     {
         notify(&generation_observer::on_before_remove, component_key);
 
-        std::erase_if(_components, [&component_key](const auto& pair) {
-            return pair.first == component_key;
+        std::erase_if(_components, [&component_key](const auto& entry) {
+            return entry.key == component_key;
         });
         _weight_overrides.erase(component_key);
 
@@ -592,11 +611,33 @@ class eg
     // Check if a component is registered by key.
     [[nodiscard]] bool has(const std::wstring& component_key) const
     {
-        return std::ranges::any_of(_components, [&component_key](const auto& pair) {
-            return pair.first == component_key;
+        return std::ranges::any_of(_components, [&component_key](const auto& entry) {
+            return entry.key == component_key;
         });
     }
 
+    // Remove all registered components, weight overrides, and groups.
+    eg& clear()
+    {
+        _components.clear();
+        _weight_overrides.clear();
+        _groups.clear();
+        return *this;
+    }
+
+    // Return the number of registered components.
+    [[nodiscard]] std::size_t size() const { return _components.size(); }
+
+    // Return all registered component keys in registration order.
+    [[nodiscard]] std::vector<std::wstring> component_keys() const
+    {
+        std::vector<std::wstring> keys;
+        keys.reserve(_components.size());
+        std::ranges::transform(_components, std::back_inserter(keys),
+            &component_entry::key);
+        return keys;
+    }
+
     // --- Seeding ---------------------------------------------------------
 
     // Seed the internal random engine. Subsequent generate() calls without
@@ -906,8 +947,11 @@ class eg
 
   private:
     // Component entry: key + owned component pointer.
-    using component_entry =
-        std::pair<std::wstring, std::unique_ptr<component>>;
+    struct component_entry
+    {
+        std::wstring key;
+        std::unique_ptr<component> comp;
+    };
 
     // Reference to a component entry for filtered generation.
     struct component_ref
@@ -928,7 +972,7 @@ class eg
     {
         for (const auto& obs : observers)
         {
-            (obs.get()->*hook)(std::forward<Args>(args)...);
+            ((*obs).*hook)(std::forward<Args>(args)...);
         }
     }
 
@@ -1067,8 +1111,8 @@ class eg
         refs.reserve(_components.size());
         std::ranges::transform(_components, std::back_inserter(refs),
             [this](const auto& entry) -> component_ref {
-                return {entry.first, std::cref(*entry.second),
-                        effective_weight(entry.first, *entry.second)};
+                return {entry.key, std::cref(*entry.comp),
+                        effective_weight(entry.key, *entry.comp)};
             });
         return refs;
     }
@@ -1082,11 +1126,11 @@ class eg
 
         auto matching = _components
             | std::views::filter([&](const auto& entry) {
-                return std::ranges::contains(component_keys, entry.first);
+                return std::ranges::contains(component_keys, entry.key);
             })
             | std::views::transform([this](const auto& entry) -> component_ref {
-                return {entry.first, std::cref(*entry.second),
-                        effective_weight(entry.first, *entry.second)};
+                return {entry.key, std::cref(*entry.comp),
+                        effective_weight(entry.key, *entry.comp)};
             });
         std::ranges::copy(matching, std::back_inserter(filtered));
 

dasmig/ext/stats_observer.hpp

@@ -429,6 +429,13 @@ class stats_observer : public generation_observer
     }
 };
 
+// Stream operator for one-liner report output.
+inline std::wostream& operator<<(std::wostream& os,
+                                  const stats_observer& stats)
+{
+    return os << stats.report();
+}
+
 } // namespace dasmig::ext
 
 #endif // DASMIG_EXT_STATS_OBSERVER_HPP

doc/usage.md

@@ -22,6 +22,8 @@ This guide covers every feature of the entity-generator library in detail. For a
 - [Event Hooks](#event-hooks)
 - [Conditional Components](#conditional-components)
 - [Generic Components](#generic-components)
+- [Entity Introspection](#entity-introspection)
+- [Generator Introspection](#generator-introspection)
 - [Extensions](#extensions)
 
 ## Defining Components
@@ -64,6 +66,8 @@ class age : public dasmig::component
 };
 ```
 
+`default_to_string()` handles `std::wstring`, `int`, `double`, `float`, `long`, and `bool`. All other types return `[?]` — override `to_string()` for custom types.
+
 ## Registering and Generating
 
 ```cpp
@@ -93,6 +97,11 @@ auto second = eg::instance().generate();
 eg::instance().unseed();
 ```
 
+**Behavior notes:**
+- `add()` with a key that already exists **replaces** the component in place, preserving registration order. Any existing weight override for that key persists.
+- `remove()` on a non-existent key is a **no-op** (does not throw).
+- `remove_group()` on a non-existent group is a **no-op**.
+
 ## Typed Retrieval
 
 ```cpp
@@ -102,8 +111,14 @@ auto entity = eg::instance().generate();
 std::wstring char_class = entity.get<std::wstring>(L"class");
 int char_age = entity.get<int>(L"age");
 
+// Type-erased access (returns const std::any&).
+const auto& raw = entity.get_any(L"class");
+
 // Check if a component exists.
 if (entity.has(L"name")) { /* ... */ }
+
+// Iterate over all keys in generation order.
+for (const auto& key : entity.keys()) { /* ... */ }
 ```
 
 ## Component Dependencies
@@ -469,6 +484,8 @@ eg::instance().clear_observers();
 
 Multiple observers fire in registration order. The same observer can be added more than once.
 
+**Thread safety:** Observers are **not** thread-safe by default. When using `generate_batch_async`, the caller is responsible for ensuring observer implementations are safe for concurrent invocation (e.g., using atomics or mutexes).
+
 The full set of hooks (6 before/after pairs + 3 single-fire hooks, 15 methods):
 
 | Event | Hook(s) |
@@ -586,6 +603,48 @@ gen.add(std::make_unique<dasmig::constant_component<int, decltype(fmt)>>(
 // to_map()["id"] == "#5"
 ```
 
+## Entity Introspection
+
+```cpp
+auto entity = eg::instance().generate();
+
+// Number of component values.
+std::size_t n = entity.size();
+
+// Check if empty.
+if (entity.empty()) { /* ... */ }
+
+// All keys in generation order.
+auto keys = entity.keys();
+
+// Type-erased access.
+const std::any& val = entity.get_any(L"class");
+
+// Seed of the entity and individual components.
+auto entity_seed = entity.seed();
+auto comp_seed = entity.seed(L"class");
+
+// Display string map.
+auto m = entity.to_map(); // map<wstring, wstring>
+```
+
+## Generator Introspection
+
+```cpp
+dasmig::eg gen;
+gen.add(std::make_unique<age>())
+   .add(std::make_unique<character_class>());
+
+// Number of registered components.
+std::size_t n = gen.size(); // 2
+
+// All registered keys in registration order.
+auto keys = gen.component_keys(); // {"age", "class"}
+
+// Remove everything (components, weight overrides, groups).
+gen.clear();
+```
+
 ## Extensions
 
 Optional headers in `dasmig/ext/` provide ready-made functionality built on the observer interface.