x-resources 1.0.0

data/lib/x/resources/batch.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "memo"
+
+module X
+  module Resources
+    # A group of stubs, no more than one lookup takes, that hydrate together in one request rather than one each
+    # @api private
+    class Batch
+      # Initialize a batch over some identifiers
+      #
+      # @api private
+      # @param klass [Class] the class of the resources, which BatchFinders extends
+      # @param ids [Array<String, Integer>] the identifiers
+      # @param client [Object] the client used to make the requests
+      # @return [Batch] a new batch
+      def initialize(klass, ids, client:)
+        @klass = klass
+        @ids = ids
+        @client = client
+        @memo = Memo.new
+        freeze
+      end
+
+      # The resource of one identifier, looking up every identifier of the batch at once
+      #
+      # @api private
+      # @param id [String, Integer] the identifier
+      # @return [Resource, nil] the resource, or nil if it was not found
+      def fetch(id) = resources[id]
+
+      private
+
+      # The resources of the batch, keyed by identifier
+      # @api private
+      # @return [Hash{Object => Resource}] the resources
+      def resources
+        @memo.fetch { @klass.find_all(@ids, client: @client).to_h { |resource| [resource.id, resource] } }
+      end
+    end
+    private_constant :Batch
+  end
+end

data/lib/x/resources/batch_finders.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "finders"
+require_relative "parallel"
+require_relative "utils"
+
+module X
+  module Resources
+    # Class methods that look resources up many at a time, extended into each resource class the API can look up that way
+    #
+    # A resource the API looks up only one at a time, such as a list, a community, or a direct message event, extends
+    # Finders alone, and so answers neither find_all nor hydrate_all, rather than answer them only to raise.
+    #
+    # Internal to x-resources: the methods it gives a resource class, such as X::Post.find_all, are public API, but the
+    # module is only how they are shared, and which classes extend or include it can change within 1.x.
+    #
+    # @api semipublic
+    module BatchFinders
+      include Finders
+
+      # Maximum number of identifiers accepted by a batch lookup endpoint
+      # @api private
+      MAX_BATCH_SIZE = 100
+
+      # Default number of batch lookups a request makes at once, which matches the chunks an upload sends at once
+      # @api private
+      DEFAULT_CONCURRENCY = 4
+
+      # The message of the error raised for a concurrency that would look nothing up
+      # @api private
+      INVALID_CONCURRENCY = "concurrency must be an Integer of at least 1, not %s"
+      private_constant :INVALID_CONCURRENCY
+
+      # The message of the error raised for resources to hydrate that are not of the class hydrating them
+      # @api private
+      FOREIGN_RESOURCE = "%s.hydrate_all hydrates %s resources, not %s"
+      private_constant :FOREIGN_RESOURCE
+
+      # Replace the resources that are not hydrated with the full resources
+      #
+      # A resource that hydrate would look up is looked up, which is a stub and also a resource a response included
+      # without every field, so what comes back is hydrated throughout. A resource that was not found is dropped, as
+      # is nil, which a reference to no resource reads as, such as the author of a post whose response named none,
+      # and a hydrated resource is kept as it is, so resources that are all hydrated need no lookup. What was found is
+      # stored in each original, so hydrating one of them afterwards costs no request, unless params override a
+      # default field or expansion parameter: what such a lookup found is not the full resource, so it is returned
+      # without being stored, and hydrating an original fetches the full resource. A resource that holds what hydrate
+      # returns, because hydrate or an earlier hydrate_all stored it, is replaced with that, and looked up again by no
+      # request, since the API bills each resource a lookup returns.
+      #
+      # @api public
+      # @param resources [Array<Resource, nil>] the resources, some of which may not be hydrated, and some nil
+      # @param client [Object] the client used to make the requests
+      # @param concurrency [Integer] the number of batch lookups made at once, four by default, which must be at
+      #   least one
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Array<Resource>] the resources, in order, with the ones that were not hydrated replaced, frozen
+      # @raise [ArgumentError] if the concurrency is less than one
+      # @raise [ArgumentError] if a resource is not of this class, which a lookup of its identifier would find
+      #   another resource for, before a request
+      # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+      # @example Look up every field of the authors of posts, the ones a search included among them
+      #   X::User.hydrate_all(posts.map(&:author), client: client)
+      # @example Expand only the authors a search did not include, which the API bills for alone
+      #   X::User.hydrate_all(posts.filter_map(&:author).select(&:stub?), client: client)
+      def hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params, &)
+        resources = resources.compact
+        validate_class!(resources)
+        partial = resources.reject { |resource| settled?(resource) }
+        replace = replacer(find_all(partial, client:, concurrency:, **params, &), params)
+        resources.filter_map { |resource| settled?(resource) ? resource.hydrate : replace.call(resource) }.freeze
+      end
+
+      # Look up many resources by identifier, in parallel batches
+      #
+      # The resources come back in the order of the identifiers they were asked for by, whatever order the batches
+      # were answered in, one for each identifier that was found, so an identifier asked for twice comes back twice,
+      # as hydrate_all keeps a resource it is given twice. Each identifier is asked for once, however often it is
+      # given.
+      #
+      # @api public
+      # @param ids [Array<String, Integer, Resource>] the identifiers, or resources of this class
+      # @param client [Object] the client used to make the requests
+      # @param concurrency [Integer] the number of batches looked up at once, four by default, which must be at least
+      #   one; each is a request of up to 100 identifiers, so a lower number spends a rate limit more slowly
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Array<Resource>] the resources that were found, one for each identifier that names one, frozen
+      # @raise [ArgumentError] if the concurrency is less than one
+      # @raise [ArgumentError] if an identifier is not one, or is a resource of another class, before a request
+      # @yieldparam problem [Problem] each problem the API reported, such as an identifier that was not found
+      # @example Look up many posts by identifier, reporting the ones that were not found
+      #   X::Post.find_all([1234567890, 1234567891], client: client) { |problem| warn problem.detail }
+      # @example Look up many posts one batch at a time, to spend a rate limit more slowly
+      #   X::Post.find_all(ids, client: client, concurrency: 1)
+      def find_all(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params, &)
+        ids = ids.map { |id| Utils.id_of(id, self) }
+        in_order_of(lookup_in_batches(endpoint!, batch_key, ids, client:, concurrency:, **params, &), ids)
+      end
+
+      private
+
+      # What replaces each resource that is not hydrated, from what a lookup found
+      #
+      # A lookup of every field found the full resource, which is stored in the original, as is a resource it did not
+      # find. A lookup of some fields found what is returned in its place, and nothing is stored.
+      #
+      # @api private
+      # @param found [Array<Resource>] the resources the lookup found
+      # @param params [Hash] the query parameters the lookup was given, merged over the default parameters
+      # @return [Proc] a callable passed a resource that is not hydrated, which returns what replaces it, or nil
+      def replacer(found, params)
+        by_id = found.to_h { |resource| [resource.id, resource] }
+        return ->(resource) { by_id[resource.id] } unless fully_requested_by?(Utils.merge_params(default_params, params))
+
+        ->(resource) { resource.__send__(:hydrated_with, by_id[resource.id]) }
+      end
+
+      # Look up values in parallel batches, asking for each value once
+      # @api private
+      # @param path [String] the batch lookup endpoint path
+      # @param key [Symbol] the query parameter the values go in, such as ids or usernames
+      # @param values [Array<String>] the values
+      # @param client [Object] the client used to make the requests
+      # @param concurrency [Integer] the number of batches looked up at once
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Array<Resource>] the resources that were found, in the order the batches were answered in
+      # @raise [ArgumentError] if the concurrency is less than one
+      # @yieldparam problem [Problem] each problem the responses reported
+      def lookup_in_batches(path, key, values, client:, concurrency:, **params, &)
+        validate_concurrency!(concurrency)
+        query = Utils.merge_params(default_params, params)
+        bodies = Parallel.map(values.uniq.each_slice(MAX_BATCH_SIZE), concurrency:) { |batch| get(path, client:, query: query.merge(Utils.query(key => batch))) }
+        bodies.flat_map { |body| collection_built_from(reporting(body, &), client:, hydrated: fully_requested_by?(query), query:) }
+      end
+
+      # Order resources as the identifiers that name them, one for each identifier
+      #
+      # An identifier is read as the resource reads its own, so that one asked for as a String of digits matches the
+      # Integer of the resource.
+      #
+      # @api private
+      # @param resources [Array<Resource>] the resources found
+      # @param ids [Array<String>] the identifiers asked for
+      # @return [Array<Resource>] the resource each identifier names, in the order of the identifiers, frozen
+      def in_order_of(resources, ids)
+        convert = Attributes::CONVERTERS.fetch(id_type)
+        by_id = resources.to_h { |resource| [resource.id, resource] }
+        ids.filter_map { |id| by_id[convert.call(id)] }.freeze
+      end
+
+      # Check whether hydrating a resource costs no request
+      # @api private
+      # @param resource [Resource] the resource
+      # @return [Boolean] true if the resource is hydrated, or holds what hydrate returns
+      def settled?(resource) = resource.hydrated? || resource.__send__(:hydration_stored?)
+
+      # Check that a number of batches to look up at once is an Integer of at least one
+      #
+      # Anything that is not an Integer, such as a String read from an environment variable, raises ArgumentError too,
+      # rather than NoMethodError from the check.
+      #
+      # @api private
+      # @param concurrency [Integer] the number of batches looked up at once
+      # @return [void]
+      # @raise [ArgumentError] if the concurrency is not an Integer, or is less than one
+      def validate_concurrency!(concurrency)
+        raise ArgumentError, format(INVALID_CONCURRENCY, concurrency.inspect) unless concurrency.instance_of?(Integer) && concurrency.positive?
+      end
+
+      # Check that resources to hydrate are of this class, whose endpoint looks them up
+      # @api private
+      # @param resources [Array<Resource>] the resources
+      # @return [void]
+      # @raise [ArgumentError] if a resource is not of this class
+      def validate_class!(resources)
+        foreign = resources.grep_v(self).first
+        raise ArgumentError, format(FOREIGN_RESOURCE, self, self, foreign.class) unless foreign.nil?
+      end
+    end
+    private_constant :BatchFinders
+  end
+end

data/lib/x/resources/bookmark_folder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module X
+  # A folder the authenticated user keeps bookmarks in
+  #
+  # The API offers no lookup of a folder, so a folder is read from the bookmark folders of the user it belongs to,
+  # which X::User#bookmark_folders pages through, and the class answers no finder. from_id builds one from its
+  # identifier, which X::User#bookmarks takes as the folder to read the posts of, but hydrate and refresh raise
+  # UnsupportedOperation for one that is not hydrated, since there is nothing to look it up with.
+  #
+  # @api public
+  class BookmarkFolder < Resource
+    # @!attribute [r] name
+    #   The name of the folder
+    #   @api public
+    #   @return [String, nil] the name
+    #   @example Get the name
+    #     folder.name # => "Ruby"
+    attribute :name
+  end
+end

data/lib/x/resources/community.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "cursor"
+require_relative "finders"
+require_relative "resource"
+
+module X
+  module Resources
+    # A community of users who post to one another
+    # @api public
+    class ::X::Community < Resource
+      extend Finders
+
+      # The mixins of the class by their full names, which YARD needs to resolve them in a class opened under X
+      #
+      # @!parse
+      #   extend X::Resources::Finders
+
+      # Every public community field
+      #
+      # A minor release may add to it the fields the API adds, so that a lookup asks for them too; see
+      # {Resource#hydrated?} for what that means for a resource looked up with a list of fields of its own.
+      FIELDS = %w[access created_at description id join_policy member_count name].freeze
+      # Maximum number of communities per page of a search
+      # @api private
+      MAX_RESULTS = 100
+      private_constant :MAX_RESULTS
+
+      class << self
+        # The API endpoint used to look up communities by identifier
+        #
+        # @api private
+        # @return [String] the endpoint
+        # @example Get the endpoint
+        #   X::Community.__send__(:endpoint) # => "communities"
+        def endpoint = "communities"
+
+        # The query parameter that selects community fields
+        #
+        # @api private
+        # @return [String] the fields parameter
+        # @example Get the fields parameter
+        #   X::Community.__send__(:fields_key) # => "community.fields"
+        def fields_key = "community.fields"
+
+        private :endpoint, :fields_key
+
+        # The default query parameters requesting every community field
+        #
+        # @api public
+        # @return [Hash{String => Array<String>}] the default query parameters
+        # @example Get the default parameters
+        #   X::Community.default_params["community.fields"]
+        def default_params = {"community.fields" => FIELDS}
+
+        # Search communities
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param client [Object] the client used to make the requests
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the matching communities
+        # @example Print the communities matching a query
+        #   X::Community.search("ruby", client: client).each { |community| puts community.name }
+        def search(query, client:, **params)
+          Cursor.__send__(:build, self, "communities/search", client:, params: {query:, max_results: MAX_RESULTS}.merge(params),
+            token_param: "next_token", min_results: 10)
+        end
+      end
+
+      # @!attribute [r] name
+      #   The name
+      #   @api public
+      #   @return [String, nil] the name
+      #   @example Get the name
+      #     community.name
+      attribute :name
+
+      # @!attribute [r] description
+      #   The description
+      #   @api public
+      #   @return [String, nil] the description
+      #   @example Get the description
+      #     community.description
+      attribute :description
+
+      # @!attribute [r] created_at
+      #   The creation time
+      #   @api public
+      #   @return [Time, nil] the creation time
+      #   @example Get the creation time
+      #     community.created_at
+      attribute :created_at, :time
+
+      # @!attribute [r] member_count
+      #   The number of members
+      #   @api public
+      #   @return [Integer, nil] the member count
+      #   @example Get the member count
+      #     community.member_count
+      attribute :member_count, :integer
+
+      # @!attribute [r] access
+      #   Who can see the community's posts, as the API names it
+      #   @api public
+      #   @return [String, nil] the access level
+      #   @example Get the access level
+      #     community.access
+      attribute :access
+
+      # @!attribute [r] join_policy
+      #   How users become members, as the API names it
+      #   @api public
+      #   @return [String, nil] the join policy
+      #   @example Get the join policy
+      #     community.join_policy
+      attribute :join_policy
+
+      # The permalink of the community
+      #
+      # @api public
+      # @return [String] the x.com address of the community
+      # @example Get the permalink
+      #   community.permalink # => "https://x.com/i/communities/1234567890"
+      def permalink = "https://x.com/i/communities/#{id}"
+
+      # The permalink of the community as a URI
+      #
+      # @api public
+      # @return [URI::Generic] the x.com address of the community
+      # @example Get the address as a URI
+      #   community.uri # => #<URI::HTTPS https://x.com/i/communities/1234567890>
+      def uri = URI(permalink)
+    end
+  end
+end