databasus_ruby 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9223ce08d06f8a4f29e700d9046bab99ee5aaec01131af37a12620cdec27b7ed
-  data.tar.gz: 1cd2c4226183d6106dd8a351e61533c2bdf513f818bb0e43f4c3dd077fe548b0
+  metadata.gz: bad2c73042db7ba0a3f3ee861359422ee14dc8a842250138e7320fe0c1f40b57
+  data.tar.gz: 963517d89578177d4f48e06e3be5c146ee973c0ca2a9163cda80bd2262d0d630
 SHA512:
-  metadata.gz: f4c7dda68f74e63dc5833e41b2aff40c730f5462920bc8aaee57549a0b435516d187d07bd6e62591d7ef10b03f863d2492d5754da422021089bcaa4226d26fe2
-  data.tar.gz: 5c59d0c7e223f8904a54de677f5083c9cd94466e16e60d082b02ef42124784e52f28c09922fbe33542bf5e7b5f5c07c3b2e7a21a5d675e96e46cda29715ba7e7
+  metadata.gz: 990c3c288bce649ac4f8ca2db43b90197bdaeb0e0e3ad34b71aadfc71db58099d1c534fcdd82c2167b1f5b6d6f3b44f1077378447f8611e37faa0d22ddcbfd17
+  data.tar.gz: e405fe4b643aceec693cdc9b6a1a8f3261a94022271428b3aaa660ae8cb5bcf1a9aa3e4fc726570edd7fd489d64c1671bd7256c198cd6060f400dbccddf6fbdb

data/README.md

@@ -109,10 +109,18 @@ A database can reach its own backups, which delegates to the `backups` endpoint
 with the same filters as `client.backups.list`:
 
 ```ruby
+database.backups(status: "COMPLETED", limit: 25)
+database.backup                                    # queue a run
+
+# or by id, from the endpoint
 client.databases.backups(database.id, status: "COMPLETED", limit: 25)
-client.databases.backup(database.id)               # queue a run
+client.databases.backup(database.id)
 ```
 
+`list`, `get`, `create`, `update` and `copy` return `DatabasusRuby::Database`
+records: payload objects that read exactly like any other response but also
+carry the two methods above.
+
 `update` posts to `/databases/update` with the id in the body, matching the API.
 There is also `test_connection_direct`, `create_readonly_user`,
 `create_replication_only_user` and `readonly?` for a payload you have not saved

data/lib/databasus_ruby/collection.rb

@@ -13,8 +13,10 @@ module DatabasusRuby
 
     attr_reader :data, :total, :limit, :offset
 
-    def initialize(data: [], total: nil, limit: nil, offset: nil)
-      @data = data.map { |item| item.is_a?(Object) ? item : Object.new(item) }
+    # `wrap` builds one entry from its raw hash; it defaults to a plain Object
+    # and endpoints pass a Record builder instead.
+    def initialize(data: [], total: nil, limit: nil, offset: nil, wrap: nil)
+      @data = data.map { |item| item.is_a?(Object) ? item : (wrap || Object.method(:new)).call(item) }
       @total = total || @data.size
       @limit = limit
       @offset = offset
@@ -22,12 +24,12 @@ module DatabasusRuby
 
     # `key` names the array inside an envelope response and is ignored for
     # bare-array responses.
-    def self.from(body, key:)
+    def self.from(body, key:, wrap: nil)
       case body
       when ::Array
-        new(data: body)
+        new(data: body, wrap: wrap)
       when Hash
-        new(data: body[key] || [], total: body["total"], limit: body["limit"], offset: body["offset"])
+        new(data: body[key] || [], total: body["total"], limit: body["limit"], offset: body["offset"], wrap: wrap)
       when nil
         new
       else

data/lib/databasus_ruby/endpoint.rb

@@ -43,14 +43,21 @@ module DatabasusRuby
       client.request(:delete, path, params: params)
     end
 
-    # Wraps a single-object response.
-    def object(response)
-      Object.new(response.body.is_a?(Hash) ? response.body : {})
+    # Wraps a single-object response. `as` names a Record subclass for the
+    # domains whose payloads carry methods of their own.
+    def object(response, as: Object)
+      build(as, response.body.is_a?(Hash) ? response.body : {})
     end
 
     # Wraps a list response; `key` names the array inside an envelope payload.
-    def collection(response, key:)
-      Collection.from(response.body, key: key)
+    def collection(response, key:, as: Object)
+      Collection.from(response.body, key: key, wrap: ->(item) { build(as, item) })
+    end
+
+    # Records need the client to reach their related endpoints; plain payload
+    # objects do not.
+    def build(klass, attributes)
+      klass <= Record ? klass.new(client, attributes) : klass.new(attributes)
     end
 
     # For endpoints that answer 200/204 with no meaningful body.

data/lib/databasus_ruby/objects/databases.rb

@@ -18,24 +18,25 @@ module DatabasusRuby
 
     # GET /databases
     def list(workspace_id: nil)
-      collection(http_get("databases", { workspace_id: workspace_id || client.workspace_id! }), key: "databases")
+      collection(http_get("databases", { workspace_id: workspace_id || client.workspace_id! }),
+                 key: "databases", as: Database)
     end
     alias all list
 
     # GET /databases/{id}
     def get(id)
-      object(http_get("databases/#{escape(id)}"))
+      object(http_get("databases/#{escape(id)}"), as: Database)
     end
     alias find get
 
     # POST /databases/create
     def create(**attributes)
-      object(http_post("databases/create", with_default_workspace(attributes)))
+      object(http_post("databases/create", with_default_workspace(attributes)), as: Database)
     end
 
     # POST /databases/update — the id travels in the body, not the path.
     def update(**attributes)
-      object(http_post("databases/update", attributes))
+      object(http_post("databases/update", attributes), as: Database)
     end
 
     # DELETE /databases/{id}
@@ -45,7 +46,7 @@ module DatabasusRuby
 
     # POST /databases/{id}/copy
     def copy(id)
-      object(http_post("databases/#{escape(id)}/copy"))
+      object(http_post("databases/#{escape(id)}/copy"), as: Database)
     end
 
     # POST /databases/{id}/test-connection — true when the database answers.
@@ -78,9 +79,8 @@ module DatabasusRuby
       readonly(**attributes).isReadOnly == true
     end
 
-    # The backups of one database, so a caller holding a database does not have
-    # to reach back for the other endpoint. Both delegate to Backups, which
-    # owns the requests.
+    # The backups of one database by id. A database returned by this endpoint
+    # answers the same two methods without the id — see Database.
     #
     #   client.databases.backups(database.id, status: "COMPLETED")
     #   client.databases.backup(database.id)          # queue a run

data/lib/databasus_ruby/record.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # A payload that remembers the client it came from, so the record can reach
+  # the endpoints related to it:
+  #
+  #   client.databases.get(id).backups(status: "COMPLETED")
+  #
+  # Plain Object stays the wrapper for nested fields and for responses that
+  # have nothing hanging off them; Record exists only for the payloads whose
+  # domain has related endpoints.
+  class Record < Object
+    attr_reader :client
+
+    def initialize(client, attributes = {})
+      @client = client
+      super(attributes)
+    end
+
+    private
+
+    # Related endpoints address the record by id, and the API omits empty
+    # fields, so a record built from a partial payload has to say so rather
+    # than sending a request with a nil id.
+    def id!
+      value = self["id"]
+      raise Error, "this #{self.class.name} has no id" if value.nil? || value.to_s.empty?
+
+      value
+    end
+  end
+end

data/lib/databasus_ruby/records/database.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # One database, as returned by the Databases endpoint.
+  #
+  #   database = client.databases.get(id)
+  #   database.backups(status: "COMPLETED")
+  #   database.backup                       # queue a run
+  #
+  # Both delegate to the Backups endpoint, which owns the requests.
+  class Database < Record
+    # Takes the same filters as Backups#list.
+    def backups(**filters)
+      client.backups.list(database_id: id!, **filters)
+    end
+
+    def backup
+      client.backups.create(database_id: id!)
+    end
+  end
+end

data/lib/databasus_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DatabasusRuby
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/databasus_ruby.rb

@@ -16,6 +16,7 @@ module DatabasusRuby
   autoload :Collection, "databasus_ruby/collection"
   autoload :Endpoint, "databasus_ruby/endpoint"
   autoload :Object, "databasus_ruby/object"
+  autoload :Record, "databasus_ruby/record"
 
   autoload :Error, "databasus_ruby/error"
   autoload :ConfigurationError, "databasus_ruby/error"
@@ -35,4 +36,6 @@ module DatabasusRuby
   autoload :Storages, "databasus_ruby/objects/storages"
   autoload :Users, "databasus_ruby/objects/users"
   autoload :Workspaces, "databasus_ruby/objects/workspaces"
+
+  autoload :Database, "databasus_ruby/records/database"
 end

data/sig/databasus_ruby.rbs

@@ -58,6 +58,21 @@ module DatabasusRuby
     def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
   end
 
+  class Record < Object
+    attr_reader client: Client
+
+    def initialize: (Client client, ?payload attributes) -> void
+
+    private
+
+    def id!: () -> String
+  end
+
+  class Database < Record
+    def backups: (**untyped) -> Collection
+    def backup: () -> Object
+  end
+
   class Collection
     include Enumerable[Object]
 
@@ -66,8 +81,14 @@ module DatabasusRuby
     attr_reader limit: Integer?
     attr_reader offset: Integer?
 
-    def initialize: (?data: Array[payload | Object], ?total: Integer?, ?limit: Integer?, ?offset: Integer?) -> void
-    def self.from: (untyped body, key: String) -> Collection
+    def initialize: (
+      ?data: Array[payload | Object],
+      ?total: Integer?,
+      ?limit: Integer?,
+      ?offset: Integer?,
+      ?wrap: ^(payload) -> Object | nil
+    ) -> void
+    def self.from: (untyped body, key: String, ?wrap: (^(payload) -> Object)?) -> Collection
     def each: () { (Object) -> void } -> Collection
             | () -> Enumerator[Object, Array[Object]]
     def size: () -> Integer
@@ -93,8 +114,9 @@ module DatabasusRuby
     def http_post: (String path, ?payload? body, ?params: payload?) -> untyped
     def http_put: (String path, ?payload? body, ?params: payload?) -> untyped
     def http_delete: (String path, ?payload? params) -> untyped
-    def object: (untyped response) -> Object
-    def collection: (untyped response, key: String) -> Collection
+    def object: (untyped response, ?as: singleton(Object)) -> Object
+    def collection: (untyped response, key: String, ?as: singleton(Object)) -> Collection
+    def build: (singleton(Object) klass, payload attributes) -> Object
     def acknowledged: (untyped response) -> bool
     def single_value: (untyped response) -> untyped
     def compact: (untyped body) -> untyped
@@ -188,12 +210,12 @@ module DatabasusRuby
 
     def list: (?workspace_id: String?) -> Collection
     def all: (?workspace_id: String?) -> Collection
-    def get: (String id) -> Object
-    def find: (String id) -> Object
-    def create: (**untyped) -> Object
-    def update: (**untyped) -> Object
+    def get: (String id) -> Database
+    def find: (String id) -> Database
+    def create: (**untyped) -> Database
+    def update: (**untyped) -> Database
     def delete: (String id) -> bool
-    def copy: (String id) -> Object
+    def copy: (String id) -> Database
     def test_connection: (String id) -> bool
     def test_connection_direct: (**untyped) -> bool
     def create_readonly_user: (**untyped) -> Object

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: databasus_ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - SamuelFCorrea
@@ -51,6 +51,8 @@ files:
 - lib/databasus_ruby/objects/storages.rb
 - lib/databasus_ruby/objects/users.rb
 - lib/databasus_ruby/objects/workspaces.rb
+- lib/databasus_ruby/record.rb
+- lib/databasus_ruby/records/database.rb
 - lib/databasus_ruby/version.rb
 - sig/databasus_ruby.rbs
 homepage: https://github.com/SamuelFCorrea/databasus_ruby