From 1048d45713cf39aee5e9724fc174e958faf8be3a Mon Sep 17 00:00:00 2001 From: Jamiu Okanlawon Date: Fri, 14 Mar 2025 13:03:05 +0100 Subject: [PATCH 1/3] chore: add new "storage" section to the documentation tab --- docs.json | 5 +++++ docs/storage/index.mdx | 0 2 files changed, 5 insertions(+) create mode 100644 docs/storage/index.mdx diff --git a/docs.json b/docs.json index 95575e1d..484f78b4 100644 --- a/docs.json +++ b/docs.json @@ -89,6 +89,11 @@ { "title": "Flutter Web", "href": "/frameworks/flutter-web" } ] }, + { + "group": "Storage", + "tab": "root", + "pages": [{ "title": "GlobeKV", "href": "/storage" }] + }, { "group": "CLI", "tab": "cli", diff --git a/docs/storage/index.mdx b/docs/storage/index.mdx new file mode 100644 index 00000000..e69de29b From 644ec33091e10c16c9f28c985b7831b10ad10e99 Mon Sep 17 00:00:00 2001 From: Jamiu Okanlawon Date: Fri, 14 Mar 2025 13:03:50 +0100 Subject: [PATCH 2/3] chore: add initial docs for globe kv --- docs/storage/index.mdx | 188 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) diff --git a/docs/storage/index.mdx b/docs/storage/index.mdx index e69de29b..3f42220e 100644 --- a/docs/storage/index.mdx +++ b/docs/storage/index.mdx @@ -0,0 +1,188 @@ +--- +title: GlobeKV +--- + +GlobeKV is a **key-value store** designed for **fast reads** and **low-latency data access**. It is ideal for **caching, user settings, session storage, and feature flags** in Flutter applications. + +Unlike traditional databases, GlobeKV **does not guarantee immediate consistency**. Updates can take up to **60 seconds** to propagate globally. This makes it great for **temporary or frequently accessed data** but unsuitable for operations requiring absolute consistency (e.g., payments, counters). + +This guide explains **how to use GlobeKV**, covering **setup, storing and retrieving data, expiration, performance, and eventual consistency**. For method details and advanced configurations, links to the API documentation are provided where relevant. + +## Setting Up GlobeKV + +### 1. Adding Globe to your Project + +Add `globe_kv` to your `pubspec.yaml`: + +```yaml +dependencies: + globe_kv: latest +``` + +Then install it: + +```bash +dart pub get +``` + +Or run this command in your terminal: + +With Dart: + +```bash +dart pub add globe_kv +``` + +With Flutter: + +```bash +flutter pub add globe_kv +``` + +### 2. Creating a Namespace + +To use GlobeKV, you need a **KV namespace**. + +Replace with steps + +### 3. Creating an Instance + +Create a new GlobeKV instance, passing in your KV namespace. + +```dart +import 'package:globe_kv/globe_kv.dart'; + +// Replace 'namespace-id' with your actual KV namespace +final kv = GlobeKV('namespace-id'); +``` + +### 4. Persist Data to Your Local Filesystem + +In development, GlobeKV will use in-memory storage so your data will be lost when the Dart app is restarted. To persist data to your local filesystem, use the GlobeFileStore instance: + +```dart +final kv = GlobeKV('namespace-id', store: GlobeFileStore()); +``` + +## Using GlobeKV + +### Storing, Retrieving, and Deleting Data + +GlobeKV is a **key-value store**, meaning you store and retrieve data using **keys**. + +#### Writing Data + +```dart +await kv.set('user:123', 'John Doe'); +``` + +#### Reading Data + +```dart +final userData = await kv.getString('user:123'); +debugPrint(userData); // Output: John Doe +``` + +#### Deleting Data + +```dart +await kv.delete('user:123'); +``` + +#### Retrieving Data + +GlobeKV **supports typed retrieval**, so you can fetch data in a specific format: + +```dart +await kv.getString('key'); // String? +await kv.getInt('key'); // int? +await kv.getBool('key'); // bool? +await kv.getBinary('key'); // List? +``` + +### Listing and Filtering Data + +When storing multiple related keys (e.g., user data), use prefixes to **group and filter keys**. + +#### Listing All Keys with a Prefix + +```dart +final result = await kv.list(prefix: 'user:'); +print(result.results.map((e) => e.key)); // ['user:123', 'user:456'] +``` + +#### Paginating Large Datasets + +By default, list() returns **up to 1000 keys per page**. If you have more, paginate: + +```dart +final result = await kv.list(prefix: 'user:', limit: 10); +if (!result.complete) { + final nextResult = await kv.list(prefix: 'user:', limit: 10, cursor: result.cursor!); +} +``` + +### Expiring Data (TTL & Absolute Expiration) + +GlobeKV supports **automatic expiration**, useful for caching API responses or managing temporary session data. + +#### Setting a Time-to-Live (TTL) + +```dart +await kv.set('user:123', 'John Doe', ttl: 5); // Expires in 5 seconds +``` + +#### Setting an Absolute Expiration Time + +```dart +await kv.set('user:123', 'John Doe', expires: DateTime.now().add(Duration(minutes: 5))); +``` + +#### When to Use TTL vs Expiration + +- TTL (time-to-live) is best for **short-lived cache** or session data. +- **Absolute expiration** is best when data must expire at a fixed point in time. + +### Performance: Hot vs Cold Reads + +#### Understanding Edge Caching + +GlobeKV uses **edge locations** (Points of Presence, POPs) to **cache data closer to users**. + +- If data is **already cached** at an edge location → **Hot Read** (Fast) +- If data **needs to be fetched** from storage → **Cold Read** (Slower) + +By default, **hot reads last 60 seconds**. + +#### Increasing Cache Duration for Faster Reads + +```dart +await kv.get('user:123', ttl: 60 * 60 * 24); // Cache for 24 hours +``` + +Use this for data that rarely changes, like feature flags or app settings. + +### Eventual Consistency + +GlobeKV is **not fully consistent**—updates may take **up to 60 seconds** to reflect globally. + +#### Good for: + +- User preferences +- Feature flags +- Non-critical cached data + +#### Not suitable for: + +- Financial transactions +- Real-time counters + +#### For Less Frequent Updates, Use a Longer Cache + +If your data doesn't change often, increasing the **TTL on reads** can improve performance: + +```dart +await kv.get('user:123', ttl: 60 * 60 * 24); // Cache for 24 hours +``` + +This reduces cold reads and improves performance for users. From d814761e702bd42bfd8946b5c3cd69fefb183cab Mon Sep 17 00:00:00 2001 From: Jamiu Okanlawon Date: Fri, 14 Mar 2025 14:16:07 +0100 Subject: [PATCH 3/3] chore: code review --- docs/storage/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/storage/index.mdx b/docs/storage/index.mdx index 3f42220e..c8e44e44 100644 --- a/docs/storage/index.mdx +++ b/docs/storage/index.mdx @@ -10,7 +10,7 @@ This guide explains **how to use GlobeKV**, covering **setup, storing and retrie ## Setting Up GlobeKV -### 1. Adding Globe to your Project +### 1. Adding GlobeKV to your Project Add `globe_kv` to your `pubspec.yaml`: