chore: add doc api examples (#91)

* chore: adding doc API examples

* chore: add CI for doc api examples

* fix: add missing await

* fix: formatting

* fix: exclude api snippets from analyzer

The code snippets require a specific method name format that fails dart analysis.

* fix: export api key as MOMENTO_API_KEY for api examples

.github/workflows/on-pull-request.yml

@@ -35,7 +35,15 @@ jobs:
         run: dart test
         env:
           TEST_API_KEY: ${{ secrets.ALPHA_TEST_AUTH_TOKEN }}
-
+
+      - name: Run examples
+        env:
+          MOMENTO_API_KEY: ${{ secrets.ALPHA_TEST_AUTH_TOKEN }}
+        run: |
+          pushd example/doc_example_apis
+            dart run doc_example_apis.dart
+          popd        
+
   readme:
     runs-on: ubuntu-latest
     steps:
@@ -50,4 +58,4 @@ jobs:
           sdk_language: Dart
           template_file: ./README.template.md
           output_file: ./README.md
-          dev_docs_slug: dart
+          dev_docs_slug: dart

analysis_options.yaml

@@ -23,6 +23,7 @@ analyzer:
  exclude:
    - lib/generated/**
    - example/flutter_chat_app/**
+   - example/doc_example_apis/**
 
 # For more information about the core and recommended set of lints, see
 # https://dart.dev/go/core-lints

example/doc_example_apis/doc_example_apis.dart

@@ -0,0 +1,109 @@
+import 'dart:io';
+import 'package:momento/momento.dart';
+import 'package:uuid/uuid.dart';
+
+Future<void> example_API_InstantiateCacheClient() async {
+  try {
+    final cacheClient = CacheClient(
+        CredentialProvider.fromEnvironmentVariable("MOMENTO_API_KEY"),
+        CacheClientConfigurations.latest(),
+        Duration(seconds: 30));
+  } catch (e) {
+    print("Unable to create cache client: $e");
+    exit(1);
+  }
+}
+
+Future<void> example_API_CreateCache(
+    CacheClient cacheClient, String cacheName) async {
+  final result = await cacheClient.createCache(cacheName);
+  switch (result) {
+    case CreateCacheAlreadyExists():
+      print("Cache already exists");
+    case CreateCacheError():
+      print("Error creating cache: $result");
+    case CreateCacheSuccess():
+      print("Successfully created the cache");
+  }
+}
+
+Future<void> example_API_ListCaches(CacheClient cacheClient) async {
+  final result = await cacheClient.listCaches();
+  switch (result) {
+    case ListCachesError():
+      print("Error listing caches: $result");
+    case ListCachesSuccess():
+      print("Successfully listed caches: ${result.cacheNames}");
+  }
+}
+
+Future<void> example_API_DeleteCache(
+    CacheClient cacheClient, String cacheName) async {
+  final result = await cacheClient.deleteCache(cacheName);
+  switch (result) {
+    case DeleteCacheError():
+      print("Error deleting cache: $result");
+      exit(1);
+    case DeleteCacheSuccess():
+      print("Successfully deleted cache");
+  }
+}
+
+Future<void> example_API_Set(
+    CacheClient cacheClient, String cacheName, Value key, Value value) async {
+  final result = await cacheClient.set(cacheName, key, value);
+  switch (result) {
+    case SetError():
+      print("Error setting key: $result");
+      exit(1);
+    case SetSuccess():
+      print("Successfully set item in the cache");
+  }
+}
+
+Future<void> example_API_Get(
+    CacheClient cacheClient, String cacheName, Value key) async {
+  final result = await cacheClient.get(cacheName, key);
+  switch (result) {
+    case GetMiss():
+      print("Key was not found in cache.");
+    case GetError():
+      print("Error getting key: $result");
+    case GetHit():
+      print("Successfully got item from cache: ${result.value}");
+  }
+}
+
+Future<void> example_API_Delete(
+    CacheClient cacheClient, String cacheName, Value key) async {
+  final result = await cacheClient.delete(cacheName, key);
+  switch (result) {
+    case DeleteError():
+      print("Error deleting key: $result");
+      exit(1);
+    case DeleteSuccess():
+      print("Successfully deleted key from cache");
+  }
+}
+
+Future<void> main() async {
+  final cacheClient = CacheClient(
+      CredentialProvider.fromEnvironmentVariable("MOMENTO_API_KEY"),
+      CacheClientConfigurations.latest(),
+      Duration(seconds: 30));
+
+  final cacheName = "doc-example-apis-${Uuid().v4()}";
+  final key = StringValue("myKey");
+  final value = StringValue("myValue");
+
+  await example_API_InstantiateCacheClient();
+  await example_API_CreateCache(cacheClient, cacheName);
+  await example_API_ListCaches(cacheClient);
+
+  await example_API_Set(cacheClient, cacheName, key, value);
+  await example_API_Get(cacheClient, cacheName, key);
+  await example_API_Delete(cacheClient, cacheName, key);
+
+  await example_API_DeleteCache(cacheClient, cacheName);
+  await cacheClient.close();
+}

lib/src/internal/control_client.dart

@@ -40,7 +40,7 @@ class ControlClient implements AbstractControlClient {
       return CreateCacheSuccess();
     } catch (e) {
       if (e is GrpcError && e.code == StatusCode.alreadyExists) {
-        return AlreadyExists();
+        return CreateCacheAlreadyExists();
       } else if (e is GrpcError) {
         return CreateCacheError(grpcStatusToSdkException(e));
       } else {

lib/src/messages/responses/cache/control/create_cache_response.dart

@@ -7,7 +7,7 @@ import 'package:momento/src/messages/responses/responses_base.dart';
 ///   switch (response) {
 ///   case CreateCacheSuccess():
 ///      // handle success
-///   case AlreadyExists():
+///   case CreateCacheAlreadyExists():
 ///      // handle already exists
 ///   case CreateCacheError():
 ///      // handle error
@@ -19,7 +19,7 @@ sealed class CreateCacheResponse {}
 class CreateCacheSuccess implements CreateCacheResponse {}
 
 /// Indicates that the cache already exists, so there was nothing to do.
-class AlreadyExists implements CreateCacheResponse {}
+class CreateCacheAlreadyExists implements CreateCacheResponse {}
 
 /// Indicates that an error occurred during the create cache request.
 ///

test/src/cache/cache_test.dart

@@ -27,7 +27,7 @@ void main() {
       switch (createResp) {
         case CreateCacheSuccess():
           fail('Expected Error but got Success');
-        case AlreadyExists():
+        case CreateCacheAlreadyExists():
           fail('Expected Error but got AlreadyExists');
         case CreateCacheError():
           expect(createResp.errorCode, MomentoErrorCode.invalidArgumentError,
@@ -51,7 +51,7 @@ void main() {
         case CreateCacheSuccess():
           expect(createResp.runtimeType, CreateCacheSuccess,
               reason: "create cache should succeed");
-        case AlreadyExists():
+        case CreateCacheAlreadyExists():
           fail('Expected Success but got AlreadyExists');
         case CreateCacheError():
           fail(