magic_map 1.0.2

A Dart package that allows JavaScript-like dot-access to deeply nested Maps and Lists.

---

# 🔮 MagicMap

`MagicMap` is a powerful Dart utility for dynamic, nested map access and mutation with dot-path syntax, glob support, immutable updates, and dynamic field access.

> Effortlessly manage deeply nested structures in a readable, type-safe-ish way.

---

## ✨ Features

- ✅ Dot-path access to deeply nested fields
- ✅ Dynamic creation of nested structures with `set`
- ✅ Immutable update API with `setImmutable`
- ✅ Bash-style glob pattern querying (`Glob`)
- ✅ JSON (de)serialization
- ✅ Dynamic dot access via `noSuchMethod`
- ✅ Supports `Map<String, dynamic>` and nested `List`s

---

## 📦 Installation

Add this to your `pubspec.yaml`:

```yaml
dependencies:
  glob: ^2.1.2

Then run:

dart pub get

---

🚀 Quick Start

7️⃣ Dynamic Dot Access (noSuchMethod)

final map = MagicMap({'person': {'name': 'Zion'}});
print(map.person.name); // Output: Zion

---

🔍 Usage Examples

1️⃣ Basic Access

final map = MagicMap({'name': 'Echezona', 'age': 24});
print(map.getPath('name')); // Output: Echezona
print(map.getPath('age'));  // Output: 24

---

2️⃣ Setting a Nested Value Dynamically

final map = MagicMap({});
map.set('user.profile.name', 'Miracle');

print(map.getPath('user.profile.name')); // Output: Miracle
print(map.toJsonString()); // {"user":{"profile":{"name":"Miracle"}}}

---

3️⃣ Immutable Update (Functional Style)

final map1 = MagicMap({'config': {'theme': 'dark'}});
final map2 = map1.setImmutable('config.theme', 'light');

print(map1.getPath('config.theme')); // Output: dark
print(map2.getPath('config.theme')); // Output: light

---

4️⃣ Glob Matching (Flexible Pattern Matching)

final data = {
  'settings': {
    'ui': {'theme': 'dark', 'font': 'Roboto'},
    'notifications': {'email': true, 'sms': false},
  }
};

final map = MagicMap(data);

final matches = map.getWithGlob('settings.ui.*');
print(matches); // Output: [dark, Roboto]

---

5️⃣ Using Lists with Glob

final data = {
  'users': [
    {'name': 'Alice', 'age': 30},
    {'name': 'Bob', 'age': 25},
  ]
};

final map = MagicMap(data);

final names = map.getWithGlob('users.[*].name');
print(names); // Output: [Alice, Bob]

---

6️⃣ JSON String Input/Output

final jsonStr = '{"app":{"version":"1.0.0","debug":false}}';
final map = MagicMap.fromJsonString(jsonStr);

print(map.getPath('app.version')); // Output: 1.0.0

map.set('app.debug', true);
print(map.toJsonString()); 
// Output: {"app":{"version":"1.0.0","debug":true}}

---

🧱 API Overview

Constructor

MagicMap(dynamic data)

Get value at dot path

map.getPath('config.theme');

Set value at dot path

map.set('config.theme', 'light');

Immutable update

final newMap = map.setImmutable('user.active', true);

Glob pattern search

map.getWithGlob('settings.ui.*');

Convert to JSON

final jsonStr = map.toJsonString();

Create from JSON

final map = MagicMap.fromJsonString(jsonStr);

---

❗Error Handling

Throws MagicMapException on:

• Accessing missing keys
• Using getPath on non-Map structure
• Invalid root data for path operations

---

🔚 License

MIT — use freely, modify wildly, and contribute happily!

---

👨‍💻 Author

Okolo Miracle Echezona
📧 [e-mail]
🌍 GitHub | LinkedIn

---