statelydb 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '039f735f87b49d58192914fdb0ff62cafce5d059980628671854026864248223'
-  data.tar.gz: 0ee06ba443aae408cb3a25d98041560a48f1ac6ddfd2ef9f25f13b62c21ee34c
+  metadata.gz: 2a342b194da9de36c892bb4d9f7c15b5904b75a07c3a5d6b2a06c94c9df7615d
+  data.tar.gz: b5d1c84628d6fff0c186efc30912b52c81e637427456647e7856099bf0218996
 SHA512:
-  metadata.gz: 83ef6dd4a7fc6c98d3668ac42544d568105d78421a7c2bc8d0d56e588b4a39eac823473f2e8e797bb339c6c04459bfc39a07457cadf21590d5d90036ff808e61
-  data.tar.gz: ff67b6ef6513ebe45df1ad0c12ca8d1906cee183e830a3d303d4cd6eda47e2bbf6a22634a55057ece224b13f473df23ad428f324c52806ab7904d76cb47ef159
+  metadata.gz: 92cc17e071ff1fd85f69c6a7716e123e81d5238727c8d09d9bf1f450e6082db65c4b724268cd4478489b532ab366a95208f8d81efc820fd697461daf5dcb740c
+  data.tar.gz: 7b90b2148bfcf696c91ed701233731dc0c7e6c027967bf266aa2cecbc023acdb5bcc3269998f997c47112de10f43555182560656e4bd73fcd29bb92092b55ca2

data/lib/api/db/put_pb.rb

@@ -7,7 +7,7 @@ require 'google/protobuf'
 require 'db/item_pb'
 
 
-descriptor_data = "\n\x0c\x64\x62/put.proto\x12\nstately.db\x1a\rdb/item.proto\"|\n\nPutRequest\x12\x19\n\x08store_id\x18\x01 \x01(\x04R\x07storeId\x12\'\n\x04puts\x18\x02 \x03(\x0b\x32\x13.stately.db.PutItemR\x04puts\x12*\n\x11schema_version_id\x18\x03 \x01(\rR\x0fschemaVersionId\"/\n\x07PutItem\x12$\n\x04item\x18\x01 \x01(\x0b\x32\x10.stately.db.ItemR\x04item\"5\n\x0bPutResponse\x12&\n\x05items\x18\x01 \x03(\x0b\x32\x10.stately.db.ItemR\x05itemsBc\n\x0e\x63om.stately.dbB\x08PutProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
+descriptor_data = "\n\x0c\x64\x62/put.proto\x12\nstately.db\x1a\rdb/item.proto\"|\n\nPutRequest\x12\x19\n\x08store_id\x18\x01 \x01(\x04R\x07storeId\x12\'\n\x04puts\x18\x02 \x03(\x0b\x32\x13.stately.db.PutItemR\x04puts\x12*\n\x11schema_version_id\x18\x03 \x01(\rR\x0fschemaVersionId\"U\n\x07PutItem\x12$\n\x04item\x18\x01 \x01(\x0b\x32\x10.stately.db.ItemR\x04item\x12$\n\x0emust_not_exist\x18\x03 \x01(\x08R\x0cmustNotExist\"5\n\x0bPutResponse\x12&\n\x05items\x18\x01 \x03(\x0b\x32\x10.stately.db.ItemR\x05itemsBc\n\x0e\x63om.stately.dbB\x08PutProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
 
 pool = Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/api/db/service_services_pb.rb

@@ -35,7 +35,7 @@ module Stately
         rpc :Get, ::Stately::Db::GetRequest, ::Stately::Db::GetResponse
         # Delete removes one or more Items from the Store by their key paths. This
         # will fail if the caller does not have permission to delete Items.
-        # Tombstones will be saved for deleted items for  time, so
+        # Tombstones will be saved for deleted items for some time, so
         # that SyncList can return information about deleted items. Deletes are
         # always applied atomically; all will fail or all will succeed.
         rpc :Delete, ::Stately::Db::DeleteRequest, ::Stately::Db::DeleteResponse

data/lib/error.rb

@@ -11,10 +11,13 @@ module StatelyDB
   # The Error class contains common StatelyDB error types.
   class Error < StandardError
     # The gRPC/Connect Code for this error.
+    # @return [Integer]
     attr_reader :code
     # The more fine-grained Stately error code, which is a human-readable string.
+    # @return [String]
     attr_reader :stately_code
     # The upstream cause of the error, if available.
+    # @return [Exception]
     attr_reader :cause
 
     # @param [String] message
@@ -53,6 +56,8 @@ module StatelyDB
       new(error.message, code: GRPC::Core::StatusCodes::UNKNOWN, stately_code: "Unknown", cause: error)
     end
 
+    # Turn this error's gRPC status code into a human-readable string. e.g. 3 -> "InvalidArgument"
+    # @return [String]
     def code_string
       self.class.grpc_code_to_string(@code)
     end

data/lib/statelydb.rb

@@ -38,6 +38,16 @@ module StatelyDB
                    token_provider: Common::Auth::Auth0TokenProvider.new,
                    endpoint: nil,
                    region: nil)
+      if store_id.nil?
+        raise StatelyDB::Error.new("store_id is required",
+                                   code: GRPC::Core::StatusCodes::INVALID_ARGUMENT,
+                                   stately_code: "InvalidArgument")
+      end
+      if schema.nil?
+        raise StatelyDB::Error.new("schema is required",
+                                   code: GRPC::Core::StatusCodes::INVALID_ARGUMENT,
+                                   stately_code: "InvalidArgument")
+      end
 
       endpoint = self.class.make_endpoint(endpoint:, region:)
       channel = Common::Net.new_channel(endpoint:)
@@ -169,12 +179,19 @@ module StatelyDB
     # Put an Item into a StatelyDB Store at the given key_path.
     #
     # @param item [StatelyDB::Item] a StatelyDB Item
+    # @param must_not_exist [Boolean] A condition that indicates this item must
+    #   not already exist at any of its key paths. If there is already an item
+    #   at one of those paths, the Put operation will fail with a
+    #   "ConditionalCheckFailed" error. Note that if the item has an
+    #   `initialValue` field in its key, that initial value will automatically
+    #   be chosen not to conflict with existing items, so this condition only
+    #   applies to key paths that do not contain the `initialValue` field.
     # @return [StatelyDB::Item] the item that was stored
     #
-    # @example
-    #   client.data.put(my_item)
-    def put(item)
-      resp = put_batch(item)
+    # @example client.data.put(my_item)
+    # @example client.data.put(my_item, must_not_exist: true)
+    def put(item, must_not_exist: false)
+      resp = put_batch({ item:, must_not_exist: })
 
       # Always return a single Item.
       resp.first
@@ -182,21 +199,32 @@ module StatelyDB
 
     # Put a batch of up to 50 Items into a StatelyDB Store.
     #
-    # @param items [StatelyDB::Item, Array<StatelyDB::Item>] the items to store. Max 50 items.
+    # @param items [StatelyDB::Item, Array<StatelyDB::Item>] the items to store.
+    # Max 50 items.
     # @return [Array<StatelyDB::Item>] the items that were stored
     #
     # @example
     #   client.data.put_batch(item1, item2)
+    # @example
+    #  client.data.put_batch({ item: item1, must_not_exist: true }, item2)
     def put_batch(*items)
-      items = Array(items).flatten
-      req = Stately::Db::PutRequest.new(
-        store_id: @store_id,
-        schema_version_id: @schema::SCHEMA_VERSION_ID,
-        puts: items.map do |item|
+      puts = Array(items).flatten.map do |input|
+        if input.is_a?(Hash)
+          item = input[:item]
           Stately::Db::PutItem.new(
-            item: item.send("marshal_stately")
+            item: item.send("marshal_stately"),
+            must_not_exist: input[:must_not_exist]
+          )
+        else
+          Stately::Db::PutItem.new(
+            item: input.send("marshal_stately")
           )
         end
+      end
+      req = Stately::Db::PutRequest.new(
+        store_id: @store_id,
+        schema_version_id: @schema::SCHEMA_VERSION_ID,
+        puts:
       )
       resp = @stub.put(req)
 
@@ -208,8 +236,8 @@ module StatelyDB
     # Delete up to 50 Items from a StatelyDB Store at the given key_paths.
     #
     # @param key_paths [String, Array<String>] the paths to the items. Max 50 key paths.
-    # @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
-    # @raise [StatelyDB::Error::NotFound] if the item is not found
+    # @raise [StatelyDB::Error] if the parameters are invalid
+    # @raise [StatelyDB::Error] if the item is not found
     # @return [void] nil
     #
     # @example
@@ -230,8 +258,8 @@ module StatelyDB
     # If the block completes successfully, the transaction is committed.
     #
     # @return [StatelyDB::Transaction::Transaction::Result] the result of the transaction
-    # @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
-    # @raise [StatelyDB::Error::NotFound] if the item is not found
+    # @raise [StatelyDB::Error] if the parameters are invalid
+    # @raise [StatelyDB::Error] if the item is not found
     # @raise [Exception] if any other exception is raised
     #
     # @example

data/lib/transaction/transaction.rb

@@ -226,6 +226,13 @@ module StatelyDB
       # the item will be returned while inside the transaction block.
       #
       # @param item [StatelyDB::Item] the item to store
+      # @param must_not_exist [Boolean] A condition that indicates this item must
+      #   not already exist at any of its key paths. If there is already an item
+      #   at one of those paths, the Put operation will fail with a
+      #   "ConditionalCheckFailed" error. Note that if the item has an
+      #   `initialValue` field in its key, that initial value will automatically
+      #   be chosen not to conflict with existing items, so this condition only
+      #   applies to key paths that do not contain the `initialValue` field.
       # @return [String, Integer] the id of the item
       #
       # @example
@@ -235,16 +242,18 @@ module StatelyDB
       #  results.puts.each do |result|
       #    puts result.key_path
       #  end
-      def put(item)
-        resp = put_batch(item)
+      def put(item, must_not_exist: false)
+        resp = put_batch({ item:, must_not_exist: })
         resp.first
       end
 
-      # Put a batch of up to 50 Items into a StatelyDB Store. Results are not returned until the transaction is
-      # committed and will be available in the Result object returned by commit. A list of identifiers
-      # for the items will be returned while inside the transaction block.
+      # Put a batch of up to 50 Items into a StatelyDB Store. Results are not
+      # returned until the transaction is committed and will be available in the
+      # Result object returned by commit. A list of identifiers for the items
+      # will be returned while inside the transaction block.
       #
-      # @param items [StatelyDB::Item, Array<StatelyDB::Item>] the items to store. Max 50 items.
+      # @param items [StatelyDB::Item, Array<StatelyDB::Item>] the items to store. Max
+      # 50 items.
       # @return [Array<StatelyDB::UUID, String, Integer, nil>] the ids of the items
       #
       # @example
@@ -255,14 +264,22 @@ module StatelyDB
       #    puts result.key_path
       #  end
       def put_batch(*items)
-        items = Array(items).flatten
+        puts = Array(items).flatten.map do |input|
+          if input.is_a?(Hash)
+            item = input[:item]
+            Stately::Db::PutItem.new(
+              item: item.send("marshal_stately"),
+              must_not_exist: input[:must_not_exist]
+            )
+          else
+            Stately::Db::PutItem.new(
+              item: input.send("marshal_stately")
+            )
+          end
+        end
         req = Stately::Db::TransactionRequest.new(
           put_items: Stately::Db::TransactionPut.new(
-            puts: items.map do |item|
-              Stately::Db::PutItem.new(
-                item: item.send("marshal_stately")
-              )
-            end
+            puts:
           )
         )
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statelydb
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Stately Cloud, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-20 00:00:00.000000000 Z
+date: 2024-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async