statelydb 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23dc2c57925814c62a9e66ab28116a244967354708275f4359e40b6e6c298e55
-  data.tar.gz: 672e5e43289d34b4c822cd3cf299d7e9e56cbef67fcbb3d9c7751a1fa4323211
+  metadata.gz: 4b6f724702d4e1c401fc77cad630c2ae1421e4ba4c1ff6918b55d3d5c8a48caa
+  data.tar.gz: e8fed1cbf6031edfdeac07cd31a168d31952655a2cc4cdc2e86ec38db9767a83
 SHA512:
-  metadata.gz: 580bdf82d80569871022b9eebddea992c4625a0e3a60c49a44d8ab77bbbdf247efee5d63b66e5792d4ca0ad48d968cea4972c725dd314b0be127f35ceff96f95
-  data.tar.gz: 5bccf7cb6f5e88a6f659b740cf34f597186ae19b7f430e5e527ec55e150431671fe0938d6c806830b952010e25db45fd665656e0b52af4d39bd3205354d2f37b
+  metadata.gz: 10386b0674c297ed70e33917792d13eb747721b5dd74041a65e2d3c00e5bd49f118a5d61812266c2fc24c3421f40f5e7504aac9eb6d686502f313c30fae99811
+  data.tar.gz: 77fc630f3658052d89ad6f2b7f627b44fc9da01436dce38c688a60fbb4a041af669980f49f6e68ad2163ba8424790a756ecef0c6e70dabf355e3e5c8bc71eaf8

data/lib/api/db/service_pb.rb

@@ -15,7 +15,7 @@ require 'api/db/sync_list_pb'
 require 'api/db/transaction_pb'
 
 
-descriptor_data = "\n\x10\x64\x62/service.proto\x12\nstately.db\x1a\x16\x64\x62/continue_list.proto\x1a\x16\x64\x62/continue_scan.proto\x1a\x0f\x64\x62/delete.proto\x1a\x0c\x64\x62/get.proto\x1a\rdb/list.proto\x1a\x0c\x64\x62/put.proto\x1a\rdb/scan.proto\x1a\x12\x64\x62/sync_list.proto\x1a\x14\x64\x62/transaction.proto2\xb1\x05\n\x0f\x44\x61tabaseService\x12;\n\x03Put\x12\x16.stately.db.PutRequest\x1a\x17.stately.db.PutResponse\"\x03\x90\x02\x02\x12;\n\x03Get\x12\x16.stately.db.GetRequest\x1a\x17.stately.db.GetResponse\"\x03\x90\x02\x01\x12\x44\n\x06\x44\x65lete\x12\x19.stately.db.DeleteRequest\x1a\x1a.stately.db.DeleteResponse\"\x03\x90\x02\x02\x12J\n\tBeginList\x12\x1c.stately.db.BeginListRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12P\n\x0c\x43ontinueList\x12\x1f.stately.db.ContinueListRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12J\n\tBeginScan\x12\x1c.stately.db.BeginScanRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12P\n\x0c\x43ontinueScan\x12\x1f.stately.db.ContinueScanRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12L\n\x08SyncList\x12\x1b.stately.db.SyncListRequest\x1a\x1c.stately.db.SyncListResponse\"\x03\x90\x02\x01\x30\x01\x12T\n\x0bTransaction\x12\x1e.stately.db.TransactionRequest\x1a\x1f.stately.db.TransactionResponse\"\x00(\x01\x30\x01\x42g\n\x0e\x63om.stately.dbB\x0cServiceProtoP\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\x10\x64\x62/service.proto\x12\nstately.db\x1a\x16\x64\x62/continue_list.proto\x1a\x16\x64\x62/continue_scan.proto\x1a\x0f\x64\x62/delete.proto\x1a\x0c\x64\x62/get.proto\x1a\rdb/list.proto\x1a\x0c\x64\x62/put.proto\x1a\rdb/scan.proto\x1a\x12\x64\x62/sync_list.proto\x1a\x14\x64\x62/transaction.proto2\xaf\x05\n\x0f\x44\x61tabaseService\x12;\n\x03Put\x12\x16.stately.db.PutRequest\x1a\x17.stately.db.PutResponse\"\x03\x90\x02\x02\x12;\n\x03Get\x12\x16.stately.db.GetRequest\x1a\x17.stately.db.GetResponse\"\x03\x90\x02\x01\x12\x44\n\x06\x44\x65lete\x12\x19.stately.db.DeleteRequest\x1a\x1a.stately.db.DeleteResponse\"\x03\x90\x02\x02\x12J\n\tBeginList\x12\x1c.stately.db.BeginListRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12P\n\x0c\x43ontinueList\x12\x1f.stately.db.ContinueListRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12J\n\tBeginScan\x12\x1c.stately.db.BeginScanRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12P\n\x0c\x43ontinueScan\x12\x1f.stately.db.ContinueScanRequest\x1a\x18.stately.db.ListResponse\"\x03\x90\x02\x01\x30\x01\x12L\n\x08SyncList\x12\x1b.stately.db.SyncListRequest\x1a\x1c.stately.db.SyncListResponse\"\x03\x90\x02\x01\x30\x01\x12R\n\x0bTransaction\x12\x1e.stately.db.TransactionRequest\x1a\x1f.stately.db.TransactionResponse(\x01\x30\x01\x42g\n\x0e\x63om.stately.dbB\x0cServiceProtoP\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/enum.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "grpc"
+require "error"
+
+module StatelyDB
+  # Base class for all Stately enums that supports undefined values
+  # and is forwards compatible with new enum values added in the Stately schema.
+  class StatelyEnum
+    # Check if the current Enum instance is a known enum member from
+    # the set. This will be false for any values that are not defined in the
+    # class definition.
+    #
+    # @return [Boolean] true if this is a known enum value, false for unknown values
+    def known?
+      !@name.start_with?("_")
+    end
+
+    # Compare this enum with another object
+    #
+    # @param other [StatelyDB::StatelyEnum, Integer, Object] the object to compare with
+    # @return [Boolean] true if equal, false otherwise
+    def ==(other)
+      case other
+      when StatelyDB::StatelyEnum
+        @value == other.value
+      when Integer
+        @value == other
+      else
+        false
+      end
+    end
+
+    # @param other [Object] the object to compare with
+    # @return [Boolean] true if equal, false otherwise
+    def eql?(other)
+      other.is_a?(self.class) && @value == other.value
+    end
+
+    # @return [Integer] the integer value of this enum
+    def to_i
+      @value
+    end
+
+    # @return [String] string representation of the enum
+    def to_s
+      known? ? @name.to_s : "UnknownEnumValue_(#{@value})"
+    end
+
+    protected
+
+    # @return [Integer] the integer value of this enum
+    attr_reader :value
+    # @return [Symbol, String] the name of this enum value, or a generated string name for unknown values
+    attr_reader :name
+
+    private
+
+    # Initialize a new Enum instance. This is private and should not be called
+    # directly; use the class methods to create instances.
+    # @param value [Integer] the integer value of the enum
+    # @param name [String, Symbol, nil] the name of the enum constant (nil for unknown values)
+    def initialize(value, name = nil)
+      @value = value.to_i
+      @name = name || "_#{@value}"
+    end
+
+    # Ensure @values is initialized for each subclass
+    # @param subclass [Class] the subclass being created
+    # @return [void]
+    def self.inherited(subclass)
+      subclass.instance_variable_set(:@values, {})
+      super
+    end
+    private_class_method :inherited
+
+    # Class methods for enum subclasses
+    class << self
+      # Returns the enum instance for a given string name
+      #
+      # @param str [String] the enum constant name
+      # @return [StatelyDB::StatelyEnum] the enum instance
+      # @raise [StatelyDB::Error] if the enum value is not defined
+      def from_string(str)
+        unless const_defined?(str)
+          raise StatelyDB::Error.new(
+            "Enum value '#{str}' is not defined in #{name}",
+            code: GRPC::Core::StatusCodes::INVALID_ARGUMENT,
+            stately_code: "InvalidArgument"
+          )
+        end
+
+        const_get(str)
+      end
+
+      # Create an enum instance from its integer value.
+      # Returns a known enum if the value is defined, otherwise creates
+      # a new instance for undefined values.
+      #
+      # @param value [Integer] the integer value
+      # @return [StatelyDB::StatelyEnum] the enum instance
+      def new(value)
+        int_value = value.to_i
+        @values[int_value] || super(int_value)
+      end
+
+      # Returns all defined enum values
+      #
+      # @return [Array<StatelyDB::StatelyEnum>] array of all defined enum instances
+      def all
+        @values.values
+      end
+
+      # Unmarshals a Stately proto enum value
+      #
+      # @param value [Integer, Symbol] the proto enum value. This can be an integer
+      # or a symbol depending on whether the proto value is defined for this version.
+      # @return [StatelyDB::StatelyEnum] the enum instance
+      def unmarshal_stately(value)
+        int_value = value.is_a?(Integer) ? value : self::Proto.resolve(value)
+        new(int_value)
+      end
+
+      private
+
+      # Defines a new enum value (used internally by generated code)
+      #
+      # @param name [Symbol] the constant name
+      # @param value [Integer] the integer value
+      # @return [StatelyDB::StatelyEnum] the created enum instance
+      def define_value(name, value)
+        # this basically allows us to bypass `new` which i want to leave as a
+        # public API that only accepts integers to be more consistent with the
+        # other languages. We manually allocate and go straight to the inherited
+        # initialize method where we set the name and value. We know they are
+        # always both defined since this is only called from the generated code.
+        enum_instance = allocate
+        enum_instance.send(:initialize, value, name)
+        @values[value] = enum_instance
+        enum_instance
+      end
+    end
+  end
+end

data/lib/key_path.rb

@@ -38,7 +38,7 @@ module StatelyDB
 
     # Appends a new path segment.
     # @param namespace [String]
-    # @param identifier [String, StatelyDB::UUID, #to_s]
+    # @param identifier [String, StatelyDB::UUID, StatelyDB::StatelyEnum, #to_s]
     # @return [StatelyDB::KeyPath]
     #
     # @example
@@ -55,6 +55,8 @@ module StatelyDB
     def self.to_key_id(value)
       if value.is_a?(StatelyDB::UUID)
         value.to_s
+      elsif value.is_a?(StatelyDB::StatelyEnum)
+        value.to_i
       elsif value.is_a?(String) && value.encoding == Encoding::BINARY
         [value].pack("m0").tr("=", "").tr("+/", "-_")
       else

data/lib/statelydb.rb

@@ -16,6 +16,7 @@ require "error"
 require "key_path"
 require "token"
 require "uuid"
+require "enum"
 
 # StatelyDB -- the home of all StatelyDB Ruby SDK classes and modules.
 module StatelyDB
@@ -173,7 +174,6 @@ module StatelyDB
     #   specified value based on lexicographic ordering.
     # @param lte [StatelyDB::KeyPath, String] filters results to only include items with a key less than or equal to the
     #   specified value based on lexicographic ordering.
-
     # @return [Array<StatelyDB::Item>, StatelyDB::Token] the list of Items and the token
     #
     # @example

data/lib/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module StatelyDB
-  VERSION = "0.34.0"
+  # @return [String] the current version of the Stately Ruby SDK
+  VERSION = "0.35.0"
 end

data/rbi/statelydb.rbi

@@ -1,6 +1,107 @@
 # typed: strong
 # A module for Stately Cloud auth code
 module StatelyDB
+  # Base class for all Stately enums that supports undefined values
+  # and is forwards compatible with new enum values added in the Stately schema.
+  class StatelyEnum
+    # Check if the current Enum instance is a known enum member from
+    # the set. This will be false for any values that are not defined in the
+    # class definition.
+    # 
+    # _@return_ — true if this is a known enum value, false for unknown values
+    sig { returns(T::Boolean) }
+    def known?; end
+
+    # Compare this enum with another object
+    # 
+    # _@param_ `other` — the object to compare with
+    # 
+    # _@return_ — true if equal, false otherwise
+    sig { params(other: T.any(StatelyDB::StatelyEnum, Integer, Object)).returns(T::Boolean) }
+    def ==(other); end
+
+    # _@param_ `other` — the object to compare with
+    # 
+    # _@return_ — true if equal, false otherwise
+    sig { params(other: Object).returns(T::Boolean) }
+    def eql?(other); end
+
+    # _@return_ — the integer value of this enum
+    sig { returns(Integer) }
+    def to_i; end
+
+    # _@return_ — string representation of the enum
+    sig { returns(String) }
+    def to_s; end
+
+    # Initialize a new Enum instance. This is private and should not be called
+    # directly; use the class methods to create instances.
+    # 
+    # _@param_ `value` — the integer value of the enum
+    # 
+    # _@param_ `name` — the name of the enum constant (nil for unknown values)
+    sig { params(value: Integer, name: T.nilable(T.any(String, Symbol))).void }
+    def initialize(value, name = nil); end
+
+    # Ensure @values is initialized for each subclass
+    # 
+    # _@param_ `subclass` — the subclass being created
+    sig { params(subclass: T::Class[T.anything]).void }
+    def self.inherited(subclass); end
+
+    # Returns the enum instance for a given string name
+    # 
+    # _@param_ `str` — the enum constant name
+    # 
+    # _@return_ — the enum instance
+    sig { params(str: String).returns(StatelyDB::StatelyEnum) }
+    def self.from_string(str); end
+
+    # Create an enum instance from its integer value.
+    # Returns a known enum if the value is defined, otherwise creates
+    # a new instance for undefined values.
+    # 
+    # _@param_ `value` — the integer value
+    # 
+    # _@return_ — the enum instance
+    sig { params(value: Integer).returns(StatelyDB::StatelyEnum) }
+    def self.new(value); end
+
+    # Returns all defined enum values
+    # 
+    # _@return_ — array of all defined enum instances
+    sig { returns(T::Array[StatelyDB::StatelyEnum]) }
+    def self.all; end
+
+    # Unmarshals a Stately proto enum value
+    # 
+    # or a symbol depending on whether the proto value is defined for this version.
+    # 
+    # _@param_ `value` — the proto enum value. This can be an integer
+    # 
+    # _@return_ — the enum instance
+    sig { params(value: T.any(Integer, Symbol)).returns(StatelyDB::StatelyEnum) }
+    def self.unmarshal_stately(value); end
+
+    # Defines a new enum value (used internally by generated code)
+    # 
+    # _@param_ `name` — the constant name
+    # 
+    # _@param_ `value` — the integer value
+    # 
+    # _@return_ — the created enum instance
+    sig { params(name: Symbol, value: Integer).returns(StatelyDB::StatelyEnum) }
+    def self.define_value(name, value); end
+
+    # _@return_ — the integer value of this enum
+    sig { returns(Integer) }
+    attr_reader :value
+
+    # _@return_ — the name of this enum value, or a generated string name for unknown values
+    sig { returns(T.any(Symbol, String)) }
+    attr_reader :name
+  end
+
   # UUID is a helper class for working with UUIDs in StatelyDB. The ruby version of a StatelyDB is a binary string,
   # and this class provides convenience methods for converting to the base16 representation specified in RFC 9562.
   # Internally this class uses the byte_string attribute to store the UUID as a string with the Encoding::ASCII_8BIT
@@ -179,7 +280,7 @@ module StatelyDB
     # ```ruby
     # keypath = KeyPath.with("genres", "rock").with("artists", "the-beatles")
     # ```
-    sig { params(namespace: String, identifier: T.nilable(T.any(String, StatelyDB::UUID, T.untyped))).returns(StatelyDB::KeyPath) }
+    sig { params(namespace: String, identifier: T.nilable(T.any(String, StatelyDB::UUID, StatelyDB::StatelyEnum, T.untyped))).returns(StatelyDB::KeyPath) }
     def self.with(namespace, identifier = nil); end
 
     # If the value is a binary string, encode it as a url-safe
@@ -267,6 +368,37 @@ module StatelyDB
     sig { params(key_paths: T.any(StatelyDB::KeyPath, String, T::Array[T.any(StatelyDB::KeyPath, String)])).returns(T::Array[StatelyDB::Item]) }
     def get_batch(*key_paths); end
 
+    # begin_list retrieves Items that start with a specified key_path_prefix
+    # from a single Group. Because it can only list items from a single Group,
+    # the key path prefix must at least start with a full Group Key (a single
+    # key segment with a namespace and an ID, e.g. `/user-1234`).
+    # 
+    # begin_list will return an empty result set if there are no items matching
+    # that key prefix. This API returns a token that you can pass to
+    # continue_list to expand the result set, or to sync_list to get updates
+    # within the result set.
+    # 
+    # You can list items of different types in a single begin_list, and you can
+    # use `isinstance` to handle different item types.
+    # 
+    # _@param_ `prefix` — The key path prefix to query for. It must be at least a full Group Key (e.g. `/user-1234`).
+    # 
+    # _@param_ `limit` — The max number of items to retrieve. If set to 0 then the full set will be returned. Defaults to 0.
+    # 
+    # _@param_ `sort_direction` — the direction to sort by (:ascending or :descending, default is :ascending).
+    # 
+    # _@param_ `item_types` — the item types to filter by. The returned items will be instances of one of these types.
+    # 
+    # _@param_ `cel_filters` — ] An optional list of item_type, cel_expression tuples that represent CEL expressions to filter the results set by. Use the cel_filter helper function to build these expressions. CEL expressions are only evaluated for the item type they are defined for, and do not affect other item types in the result set. This means if an item type has no CEL filter and there are no item_type filters constraints, it will be included in the result set. In the context of a CEL expression, the key-word `this` refers to the item being evaluated, and property properties should be accessed by the names as they appear in schema -- not necessarily as they appear in the generated code for a particular language. For example, if you have a `Movie` item type with the property `rating`, you could write a CEL expression like `this.rating == 'R'` to return only movies that are rated `R`. Find the full CEL language definition here: https://github.com/google/cel-spec/blob/master/doc/langdef.md
+    # 
+    # _@param_ `gt` — filters results to only include items with a key greater than the specified value based on lexicographic ordering.
+    # 
+    # _@param_ `gte` — filters results to only include items with a key greater than or equal to the specified value based on lexicographic ordering.
+    # 
+    # _@param_ `lt` — filters results to only include items with a key less than the specified value based on lexicographic ordering.
+    # 
+    # _@param_ `lte` — filters results to only include items with a key less than or equal to the specified value based on lexicographic ordering.
+    # 
     # _@return_ — the list of Items and the token
     # 
     # ```ruby
@@ -274,15 +406,15 @@ module StatelyDB
     # ```
     sig do
       params(
-        prefix: T.untyped,
-        limit: T.untyped,
-        sort_direction: T.untyped,
-        item_types: T.untyped,
-        cel_filters: T.untyped,
-        gt: T.untyped,
-        gte: T.untyped,
-        lt: T.untyped,
-        lte: T.untyped
+        prefix: T.any(StatelyDB::KeyPath, String),
+        limit: Integer,
+        sort_direction: T.any(Symbol, String, Integer),
+        item_types: T::Array[T.any(T.class_of(StatelyDB::Item), String)],
+        cel_filters: T::Array[T.any(T::Array[T.any(T::Class[T.anything], String)], String)],
+        gt: T.nilable(T.any(StatelyDB::KeyPath, String)),
+        gte: T.nilable(T.any(StatelyDB::KeyPath, String)),
+        lt: T.nilable(T.any(StatelyDB::KeyPath, String)),
+        lte: T.nilable(T.any(StatelyDB::KeyPath, String))
       ).returns(T.any(T::Array[StatelyDB::Item], StatelyDB::Token))
     end
     def begin_list(prefix, limit: 100, sort_direction: :ascending, item_types: [], cel_filters: [], gt: nil, gte: nil, lt: nil, lte: nil); end

data/sig/statelydb.rbs

@@ -1,6 +1,93 @@
 # A module for Stately Cloud auth code
 module StatelyDB
-  VERSION: untyped
+  VERSION: String
+
+  # Base class for all Stately enums that supports undefined values
+  # and is forwards compatible with new enum values added in the Stately schema.
+  class StatelyEnum
+    # Check if the current Enum instance is a known enum member from
+    # the set. This will be false for any values that are not defined in the
+    # class definition.
+    # 
+    # _@return_ — true if this is a known enum value, false for unknown values
+    def known?: () -> bool
+
+    # Compare this enum with another object
+    # 
+    # _@param_ `other` — the object to compare with
+    # 
+    # _@return_ — true if equal, false otherwise
+    def ==: ((StatelyDB::StatelyEnum | Integer | Object) other) -> bool
+
+    # _@param_ `other` — the object to compare with
+    # 
+    # _@return_ — true if equal, false otherwise
+    def eql?: (Object other) -> bool
+
+    # _@return_ — the integer value of this enum
+    def to_i: () -> Integer
+
+    # _@return_ — string representation of the enum
+    def to_s: () -> String
+
+    # Initialize a new Enum instance. This is private and should not be called
+    # directly; use the class methods to create instances.
+    # 
+    # _@param_ `value` — the integer value of the enum
+    # 
+    # _@param_ `name` — the name of the enum constant (nil for unknown values)
+    def initialize: (Integer value, ?(String | Symbol)? name) -> void
+
+    # Ensure @values is initialized for each subclass
+    # 
+    # _@param_ `subclass` — the subclass being created
+    def self.inherited: (Class subclass) -> void
+
+    # Returns the enum instance for a given string name
+    # 
+    # _@param_ `str` — the enum constant name
+    # 
+    # _@return_ — the enum instance
+    def self.from_string: (String str) -> StatelyDB::StatelyEnum
+
+    # Create an enum instance from its integer value.
+    # Returns a known enum if the value is defined, otherwise creates
+    # a new instance for undefined values.
+    # 
+    # _@param_ `value` — the integer value
+    # 
+    # _@return_ — the enum instance
+    def self.new: (Integer value) -> StatelyDB::StatelyEnum
+
+    # Returns all defined enum values
+    # 
+    # _@return_ — array of all defined enum instances
+    def self.all: () -> ::Array[StatelyDB::StatelyEnum]
+
+    # Unmarshals a Stately proto enum value
+    # 
+    # or a symbol depending on whether the proto value is defined for this version.
+    # 
+    # _@param_ `value` — the proto enum value. This can be an integer
+    # 
+    # _@return_ — the enum instance
+    def self.unmarshal_stately: ((Integer | Symbol) value) -> StatelyDB::StatelyEnum
+
+    # Defines a new enum value (used internally by generated code)
+    # 
+    # _@param_ `name` — the constant name
+    # 
+    # _@param_ `value` — the integer value
+    # 
+    # _@return_ — the created enum instance
+    def self.define_value: (Symbol name, Integer value) -> StatelyDB::StatelyEnum
+
+    # _@return_ — the integer value of this enum
+    attr_reader value: Integer
+
+    # _@return_ — the name of this enum value, or a generated string name for unknown values
+    attr_reader name: (Symbol | String)
+  end
 
   # UUID is a helper class for working with UUIDs in StatelyDB. The ruby version of a StatelyDB is a binary string,
   # and this class provides convenience methods for converting to the base16 representation specified in RFC 9562.
@@ -149,7 +236,7 @@ module StatelyDB
     # ```ruby
     # keypath = KeyPath.with("genres", "rock").with("artists", "the-beatles")
     # ```
-    def self.with: (String namespace, ?(String | StatelyDB::UUID | _ToS)? identifier) -> StatelyDB::KeyPath
+    def self.with: (String namespace, ?(String | StatelyDB::UUID | StatelyDB::StatelyEnum | _ToS)? identifier) -> StatelyDB::KeyPath
 
     # If the value is a binary string, encode it as a url-safe
     # base64 string with padding removed.
@@ -228,21 +315,52 @@ module StatelyDB
     # ```
     def get_batch: (*(StatelyDB::KeyPath | String | ::Array[(StatelyDB::KeyPath | String)]) key_paths) -> ::Array[StatelyDB::Item]
 
+    # begin_list retrieves Items that start with a specified key_path_prefix
+    # from a single Group. Because it can only list items from a single Group,
+    # the key path prefix must at least start with a full Group Key (a single
+    # key segment with a namespace and an ID, e.g. `/user-1234`).
+    # 
+    # begin_list will return an empty result set if there are no items matching
+    # that key prefix. This API returns a token that you can pass to
+    # continue_list to expand the result set, or to sync_list to get updates
+    # within the result set.
+    # 
+    # You can list items of different types in a single begin_list, and you can
+    # use `isinstance` to handle different item types.
+    # 
+    # _@param_ `prefix` — The key path prefix to query for. It must be at least a full Group Key (e.g. `/user-1234`).
+    # 
+    # _@param_ `limit` — The max number of items to retrieve. If set to 0 then the full set will be returned. Defaults to 0.
+    # 
+    # _@param_ `sort_direction` — the direction to sort by (:ascending or :descending, default is :ascending).
+    # 
+    # _@param_ `item_types` — the item types to filter by. The returned items will be instances of one of these types.
+    # 
+    # _@param_ `cel_filters` — ] An optional list of item_type, cel_expression tuples that represent CEL expressions to filter the results set by. Use the cel_filter helper function to build these expressions. CEL expressions are only evaluated for the item type they are defined for, and do not affect other item types in the result set. This means if an item type has no CEL filter and there are no item_type filters constraints, it will be included in the result set. In the context of a CEL expression, the key-word `this` refers to the item being evaluated, and property properties should be accessed by the names as they appear in schema -- not necessarily as they appear in the generated code for a particular language. For example, if you have a `Movie` item type with the property `rating`, you could write a CEL expression like `this.rating == 'R'` to return only movies that are rated `R`. Find the full CEL language definition here: https://github.com/google/cel-spec/blob/master/doc/langdef.md
+    # 
+    # _@param_ `gt` — filters results to only include items with a key greater than the specified value based on lexicographic ordering.
+    # 
+    # _@param_ `gte` — filters results to only include items with a key greater than or equal to the specified value based on lexicographic ordering.
+    # 
+    # _@param_ `lt` — filters results to only include items with a key less than the specified value based on lexicographic ordering.
+    # 
+    # _@param_ `lte` — filters results to only include items with a key less than or equal to the specified value based on lexicographic ordering.
+    # 
     # _@return_ — the list of Items and the token
     # 
     # ```ruby
     # client.data.begin_list("/ItemType-identifier", limit: 10, sort_direction: :ascending)
     # ```
     def begin_list: (
-                      untyped prefix,
-                      ?limit: untyped,
-                      ?sort_direction: untyped,
-                      ?item_types: untyped,
-                      ?cel_filters: untyped,
-                      ?gt: untyped,
-                      ?gte: untyped,
-                      ?lt: untyped,
-                      ?lte: untyped
+                      (StatelyDB::KeyPath | String) prefix,
+                      ?limit: Integer,
+                      ?sort_direction: (Symbol | String | Integer),
+                      ?item_types: ::Array[(singleton(StatelyDB::Item) | String)],
+                      ?cel_filters: ::Array[(::Array[(Class | String)] | String)],
+                      ?gt: (StatelyDB::KeyPath | String)?,
+                      ?gte: (StatelyDB::KeyPath | String)?,
+                      ?lt: (StatelyDB::KeyPath | String)?,
+                      ?lte: (StatelyDB::KeyPath | String)?
                     ) -> (::Array[StatelyDB::Item] | StatelyDB::Token)
 
     # continue_list takes the token from a begin_list call and returns the next

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statelydb
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Stately Cloud, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-28 00:00:00.000000000 Z
+date: 2025-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -115,6 +115,7 @@ files:
 - lib/common/build_filters.rb
 - lib/common/error_interceptor.rb
 - lib/common/net/conn.rb
+- lib/enum.rb
 - lib/error.rb
 - lib/key_path.rb
 - lib/stately_codes.rb