x-resources 1.0.0

data/lib/x/resources/lookups/posts.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative "../post"
+require_relative "../post_usage"
+
+module X
+  module Resources
+    module Lookups
+      # Look up, search, and count posts, and report how many posts the app has read, mixed into a client through API
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, and some of them need the methods of another,
+      # so include API rather than this module alone.
+      #
+      # @api semipublic
+      module Posts
+        # Look up a post by identifier
+        #
+        # @api public
+        # @param id [String, Integer, Post] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Post, nil] the post or nil if the post was not found
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a post
+        #   client.find_post(1234567890).text
+        def find_post(id, **params, &)
+          Post.find(id, client: self, **params, &)
+        end
+
+        # Look up a post by identifier, which must exist
+        #
+        # @api public
+        # @param id [String, Integer, Post] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Post] the post
+        # @raise [MissingResource] if the post was not found
+        # @example Look up a post
+        #   client.find_post!(1234567890).text
+        def find_post!(id, **params)
+          Post.find!(id, client: self, **params)
+        end
+
+        # Look up many posts by identifier, in parallel batches
+        #
+        # @api public
+        # @param ids [Array<String, Integer, Post>] the identifiers
+        # @param concurrency [Integer] the number of batches looked up at once, which must be at least one; each is
+        #   a request of up to 100 posts, so a lower number spends a rate limit more slowly
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Array<Post>] the posts that were found
+        # @raise [ArgumentError] if the concurrency is less than one
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up many posts
+        #   client.find_all_posts([1234567890, 1234567891])
+        # @example Look up many posts one batch at a time
+        #   client.find_all_posts(ids, concurrency: 1)
+        def find_all_posts(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+          Post.find_all(ids, client: self, concurrency:, **params, &)
+        end
+
+        # Search recent posts
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the matching posts
+        # @example Print posts about Ruby
+        #   client.search_posts("ruby -is:retweet").each { |post| puts post.text }
+        def search_posts(query, **params)
+          Post.search(query, client: self, **params)
+        end
+
+        # The posts of the authenticated user that other users have reposted
+        #
+        # @api public
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the reposted posts
+        # @example Print the reposted posts
+        #   client.reposts_of_me.each { |post| puts post.text }
+        def reposts_of_me(**params)
+          Post.reposts_of_me(client: self, **params)
+        end
+
+        # Search the full archive of posts
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the matching posts
+        # @example Print every post about Ruby
+        #   client.search_all_posts("ruby -is:retweet").each { |post| puts post.text }
+        def search_all_posts(query, **params)
+          Post.search_all(query, client: self, **params)
+        end
+
+        # Count the recent posts that match a query, without reading them
+        #
+        # The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs
+        # with OAuth 1.0a counts with a copy that authenticates as the app.
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters, such as start_time and end_time, and max_pages, the most pages of
+        #   counts to request
+        # @return [Integer] the number of matching posts
+        # @example Count the recent posts about Ruby with an app-only client
+        #   client.count_posts("ruby")
+        def count_posts(query, **params) = Post.count(query, client: self, **params) # steep:ignore DifferentMethodParameterKind
+
+        # Count the posts from the full archive that match a query, without reading them
+        #
+        # The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs
+        # with OAuth 1.0a counts with a copy that authenticates as the app. A client signed in with OAuth 2.0 as a user
+        # that holds no credentials of the app counts as the user, which the full archive refuses with X::Forbidden.
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters, such as start_time and end_time, and the max_pages of
+        #   X::Post.count_all, which limits the pages of counts requested
+        # @return [Integer] the number of matching posts
+        # @example Count every post about Ruby from 2024
+        #   client.count_all_posts("ruby", start_time: "2024-01-01T00:00:00Z", end_time: "2025-01-01T00:00:00Z")
+        def count_all_posts(query, **params) = Post.count_all(query, client: self, **params) # steep:ignore DifferentMethodParameterKind
+
+        # Count the posts from the last seven days that match a query, by period
+        #
+        # The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs
+        # with OAuth 1.0a counts with a copy that authenticates as the app.
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters, such as granularity, which is day by default, and max_pages, the most
+        #   pages of counts to request
+        # @return [Hash{Range<Time> => Integer}] the number of matching posts, keyed by the time each period spans,
+        #   from its start up to, but not including, its end, oldest first
+        # @example Count the recent posts about Ruby by hour
+        #   client.count_posts_by_period("ruby", granularity: "hour")
+        def count_posts_by_period(query, **params) = Post.count_by_period(query, client: self, **params) # steep:ignore DifferentMethodParameterKind
+
+        # Count the posts from the full archive that match a query, by period
+        #
+        # The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs
+        # with OAuth 1.0a counts with a copy that authenticates as the app. A client signed in with OAuth 2.0 as a user
+        # that holds no credentials of the app counts as the user, which the full archive refuses with X::Forbidden.
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters, such as granularity, which is day by default, and the max_pages of
+        #   X::Post.count_all_by_period, which limits the pages of counts requested
+        # @return [Hash{Range<Time> => Integer}] the number of matching posts, keyed by the time each period spans,
+        #   from its start up to, but not including, its end, oldest first
+        # @example Count the posts about Ruby by day in 2024
+        #   client.count_all_posts_by_period("ruby", start_time: "2024-01-01T00:00:00Z", end_time: "2025-01-01T00:00:00Z")
+        def count_all_posts_by_period(query, **params) = Post.count_all_by_period(query, client: self, **params) # steep:ignore DifferentMethodParameterKind
+
+        # Look up how many posts the app's project has read
+        #
+        # The usage endpoint takes app-only authentication alone, so a client that signs with OAuth 1.0a looks it up
+        # with a copy that authenticates as the app, and one signed in with OAuth 2.0 as a user that holds no
+        # credentials of the app is refused with X::Forbidden.
+        #
+        # A response that holds no usage returns nil, as current_user does for a users/me that holds no user, and
+        # passes the problems it reported to the block, if there is one.
+        #
+        # @api public
+        # @param params [Hash] query parameters, such as days, the number of days to report, which is 7 by default
+        # @return [PostUsage, nil] the usage, or nil if the response holds none
+        # @yieldparam problem [Problem] each problem the API reported
+        # @example Check how much of the monthly cap remains
+        #   usage = client.post_usage
+        #   usage.project_cap - usage.project_usage if usage
+        def post_usage(**params, &) = PostUsage.current(client: self, **params, &)
+
+        # Look up how many posts the app's project has read, which must be returned
+        #
+        # @api public
+        # @param params [Hash] query parameters, such as days, the number of days to report, which is 7 by default
+        # @return [PostUsage] the usage
+        # @raise [MissingResource] if the API returns no usage
+        # @example Check how much of the monthly cap remains
+        #   usage = client.post_usage!
+        #   usage.project_cap - usage.project_usage
+        def post_usage!(**params) = PostUsage.current!(client: self, **params)
+
+        alias_method :find_tweet, :find_post
+        alias_method :find_tweet!, :find_post!
+        alias_method :find_all_tweets, :find_all_posts
+        alias_method :search_tweets, :search_posts
+        alias_method :search_all_tweets, :search_all_posts
+        alias_method :retweets_of_me, :reposts_of_me
+        alias_method :count_tweets, :count_posts
+        alias_method :count_all_tweets, :count_all_posts
+        alias_method :count_tweets_by_period, :count_posts_by_period
+        alias_method :count_all_tweets_by_period, :count_all_posts_by_period
+      end
+    end
+  end
+end

data/lib/x/resources/lookups/spaces.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../space"
+
+module X
+  module Resources
+    module Lookups
+      # Look up and search spaces, mixed into a client through API
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, and some of them need the methods of another,
+      # so include API rather than this module alone.
+      #
+      # @api semipublic
+      module Spaces
+        # Look up a space by identifier
+        #
+        # @api public
+        # @param id [String, Integer, Space] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Space, nil] the space or nil if the space was not found
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a space
+        #   client.find_space("1DXxyRYNejbKM").title
+        def find_space(id, **params, &)
+          Space.find(id, client: self, **params, &)
+        end
+
+        # Look up a space by identifier, which must exist
+        #
+        # @api public
+        # @param id [String, Integer, Space] the identifier
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Space] the space
+        # @raise [MissingResource] if the space was not found
+        # @example Look up a space
+        #   client.find_space!("1DXxyRYNejbKM").title
+        def find_space!(id, **params)
+          Space.find!(id, client: self, **params)
+        end
+
+        # Look up many spaces by identifier, in parallel batches
+        #
+        # @api public
+        # @param ids [Array<String, Integer, Space>] the identifiers
+        # @param concurrency [Integer] the number of batches looked up at once, which must be at least one
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Array<Space>] the spaces that were found
+        # @raise [ArgumentError] if the concurrency is less than one
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up many spaces
+        #   client.find_all_spaces(["1DXxyRYNejbKM", "1OwGWzarWnNKQ"]).map(&:title)
+        def find_all_spaces(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+          Space.find_all(ids, client: self, concurrency:, **params, &)
+        end
+
+        # Look up the live and scheduled spaces many users created, in parallel batches
+        #
+        # @api public
+        # @param users [Array<User, String, Integer>] the users who created the spaces, or their identifiers
+        # @param concurrency [Integer] the number of batches looked up at once, which must be at least one
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Array<Space>] the spaces, frozen, empty if the users created none
+        # @raise [ArgumentError] if a user is not a user or the identifier of one, or the concurrency is less than
+        #   one, before a request
+        # @yieldparam problem [Problem] each problem the API reported
+        # @example Print the live spaces a user created
+        #   client.find_all_spaces_by_creator([7505382]).select { |space| space.state.eql?("live") }.map(&:title)
+        def find_all_spaces_by_creator(users, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+          Space.find_all_by_creator(users, client: self, concurrency:, **params, &)
+        end
+
+        # Search spaces by their titles
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters merged over the default parameters, such as state: live or scheduled
+        # @return [Cursor] a cursor over the matching spaces
+        # @example Print the live spaces about Ruby
+        #   client.search_spaces("ruby", state: "live").each { |space| puts space.title }
+        def search_spaces(query, **params)
+          Space.search(query, client: self, **params)
+        end
+      end
+    end
+  end
+end

data/lib/x/resources/lookups/trends.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../personalized_trend"
+require_relative "../trend"
+
+module X
+  module Resources
+    module Lookups
+      # Read the topics trending in a place, and for the authenticated user, mixed into a client through API
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, so include API rather than this module alone.
+      #
+      # @api semipublic
+      module Trends
+        # The topics trending in a place
+        #
+        # @api public
+        # @param woeid [Integer, String] the Yahoo! Where On Earth identifier of the place, such as 1 for the world
+        # @param params [Hash] query parameters, such as max_trends, which is 50, the most the API returns, unless given
+        # @return [Array<Trend>] the trends, frozen
+        # @raise [ArgumentError] if the WOEID is not a number, before a request
+        # @example Print the ten topics trending most in the world
+        #   client.trends(1, max_trends: 10).each { |trend| puts trend.name }
+        def trends(woeid, **params) = Trend.at(woeid, client: self, **params)
+
+        # The topics trending for the authenticated user
+        #
+        # @api public
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Array<PersonalizedTrend>] the trends, frozen
+        # @example Print the topics trending for the authenticated user
+        #   client.personalized_trends.each { |trend| puts trend.name }
+        def personalized_trends(**params) = PersonalizedTrend.all(client: self, **params)
+      end
+    end
+  end
+end

data/lib/x/resources/lookups/users.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require_relative "../user"
+
+module X
+  module Resources
+    module Lookups
+      # Look up and search users, and the authenticated user, mixed into a client through API
+      #
+      # Internal to x-resources: X::Resources::API includes it, and its methods are public API of the client that
+      # includes API, but the module is only how they are grouped, and some of them need the methods of another,
+      # so include API rather than this module alone.
+      #
+      # @api semipublic
+      module Users
+        # Look up a user by identifier or username
+        #
+        # @api public
+        # @param id_or_username [Integer, User, String] an identifier or a user, or a username
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User, nil] the user or nil if the user was not found
+        # @example Look up a user by username
+        #   client.find_user("sferik")
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a user by identifier
+        #   client.find_user(7505382)
+        def find_user(id_or_username, **params, &)
+          User.find(id_or_username, client: self, **params, &)
+        end
+
+        # Look up a user by identifier or username, which must exist
+        #
+        # @api public
+        # @param id_or_username [Integer, User, String] an identifier or a user, or a username
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User] the user
+        # @raise [MissingResource] if the user was not found
+        # @example Look up a user by username
+        #   client.find_user!("sferik")
+        def find_user!(id_or_username, **params)
+          User.find!(id_or_username, client: self, **params)
+        end
+
+        # Look up a user by username
+        #
+        # It looks every value up as a username, a String of digits as the account whose handle is that number, as
+        # find_user looks up any String, so code that reads a value from elsewhere says which it means, as
+        # find_user_by_id does.
+        #
+        # @api public
+        # @param username [String] the username, with or without a leading at sign
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User, nil] the user or nil if the user was not found
+        # @raise [ArgumentError] if the value is not a username
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a user whose username is a number
+        #   client.find_user_by_username("1234567890")
+        def find_user_by_username(username, **params, &)
+          User.find_by_username(username, client: self, **params, &)
+        end
+
+        # Look up a user by username, which must exist
+        #
+        # @api public
+        # @param username [String] the username, with or without a leading at sign
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User] the user
+        # @raise [ArgumentError] if the value is not a username
+        # @raise [MissingResource] if the user was not found
+        # @example Look up a user by username
+        #   client.find_user_by_username!("sferik")
+        def find_user_by_username!(username, **params)
+          User.find_by_username!(username, client: self, **params)
+        end
+
+        # Look up a user by identifier
+        #
+        # A String of digits is an identifier, as it is read from a response or an environment variable, so this
+        # looks the account that number identifies up, where find_user would take it for a username.
+        #
+        # @api public
+        # @param id [String, Integer, User] the identifier, or a user
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User, nil] the user or nil if the user was not found
+        # @raise [ArgumentError] if the value is not an identifier
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up a user by an identifier read as a String
+        #   client.find_user_by_id(ENV.fetch("USER_ID"))
+        def find_user_by_id(id, **params, &)
+          User.find_by_id(id, client: self, **params, &)
+        end
+
+        # Look up a user by identifier, which must exist
+        #
+        # @api public
+        # @param id [String, Integer, User] the identifier, or a user
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User] the user
+        # @raise [ArgumentError] if the value is not an identifier
+        # @raise [MissingResource] if the user was not found
+        # @example Look up a user by an identifier read as a String
+        #   client.find_user_by_id!("7505382")
+        def find_user_by_id!(id, **params)
+          User.find_by_id!(id, client: self, **params)
+        end
+
+        # Look up many users by identifier or username, in parallel batches
+        #
+        # @api public
+        # @param ids_or_usernames [Array<Integer, User, String>] identifiers or users, or usernames
+        # @param concurrency [Integer] the number of batches looked up at once, which must be at least one; each is
+        #   a request of up to 100 users, so a lower number spends a rate limit more slowly
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Array<User>] the users that were found
+        # @raise [ArgumentError] if the concurrency is less than one
+        # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+        # @example Look up many users by username
+        #   client.find_all_users(["sferik", "gem"])
+        # @example Look up many users one batch at a time
+        #   client.find_all_users(ids, concurrency: 1)
+        def find_all_users(ids_or_usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+          User.find_all(ids_or_usernames, client: self, concurrency:, **params, &)
+        end
+
+        # Look up many users by username, in parallel batches
+        #
+        # It looks every value up as a username, Strings of digits as the accounts whose handles are those numbers,
+        # as find_all_users looks up any String, so code that reads values from elsewhere says which it means, as
+        # find_all_users_by_id does.
+        #
+        # @api public
+        # @param usernames [Array<String>] the usernames, with or without leading at signs
+        # @param concurrency [Integer] the number of batches looked up at once, which must be at least one
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Array<User>] the users that were found
+        # @raise [ArgumentError] if a value is not a username, or if the concurrency is less than one
+        # @yieldparam problem [Problem] each problem the API reported, such as a username that was not found
+        # @example Look up many users by username
+        #   client.find_all_users_by_username(["sferik", "1234567890"])
+        def find_all_users_by_username(usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+          User.find_all_by_username(usernames, client: self, concurrency:, **params, &)
+        end
+
+        # Look up many users by identifier, in parallel batches
+        #
+        # A String of digits is an identifier, as it is read from a response or an environment variable, so this
+        # looks the accounts those numbers identify up, where find_all_users would take them for usernames.
+        #
+        # @api public
+        # @param ids [Array<String, Integer, User>] the identifiers, or users
+        # @param concurrency [Integer] the number of batches looked up at once, which must be at least one
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Array<User>] the users that were found
+        # @raise [ArgumentError] if a value is not an identifier, or if the concurrency is less than one
+        # @yieldparam problem [Problem] each problem the API reported, such as an identifier that was not found
+        # @example Look up many users by identifier, read as Strings
+        #   client.find_all_users_by_id(ENV.fetch("USER_IDS").split(","))
+        def find_all_users_by_id(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
+          User.find_all_by_id(ids, client: self, concurrency:, **params, &)
+        end
+
+        # Look up the authenticated user
+        #
+        # Each call looks the user up, as X::User.current does, so its counts and profile are as they are now. Keep
+        # the user it returns to read them again without a request.
+        #
+        # @api public
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User, nil] the authenticated user, or nil if the API returns none
+        # @yieldparam problem [Problem] each problem the API reported
+        # @example Print the name of the authenticated user
+        #   puts client.current_user&.name
+        def current_user(**params, &)
+          User.current(client: self, **params, &)&.tap { |user| Utils.remember_user_id(self, user.id) }
+        end
+
+        # Look up the authenticated user, who must be found
+        #
+        # Each call looks the user up, as X::User.current! does, so its counts and profile are as they are now. Keep
+        # the user it returns to read them again without a request.
+        #
+        # @api public
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [User] the authenticated user
+        # @raise [MissingResource] if the API returns no user
+        # @example Print the home timeline of the authenticated user
+        #   client.current_user!.home_timeline.each { |post| puts post.text }
+        def current_user!(**params)
+          User.current!(client: self, **params).tap { |user| Utils.remember_user_id(self, user.id) }
+        end
+
+        # The identifier of the authenticated user, from an OAuth 1.0a token if possible
+        #
+        # An OAuth 1.0a access token begins with the identifier of its user, so a client that holds one needs no
+        # lookup. Any other client looks the user up the first time, unless current_user or current_user! already
+        # has, and keeps the identifier, which never changes, for as long as it holds the same authenticator, since
+        # a client whose credentials change authenticates as someone else. An X::Client keeps it even when frozen; a
+        # frozen client without memoize keeps nothing, and looks the user up each time.
+        #
+        # @api public
+        # @return [Integer] the identifier
+        # @raise [MissingResource] if the user is looked up and the API returns none
+        # @example Get the identifier of the authenticated user
+        #   client.current_user_id # => 7505382
+        def current_user_id = Utils.authenticated_user_id(self) || Utils.remembered_user_id(self) || current_user!.id
+
+        # Search users
+        #
+        # @api public
+        # @param query [String] the search query
+        # @param params [Hash] query parameters merged over the default parameters
+        # @return [Cursor] a cursor over the matching users
+        # @example Print the users matching a query
+        #   client.search_users("ruby").each { |user| puts user.username }
+        def search_users(query, **params)
+          User.search(query, client: self, **params)
+        end
+      end
+    end
+  end
+end

data/lib/x/resources/lookups.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lookups/communities"
+require_relative "lookups/direct_messages"
+require_relative "lookups/lists"
+require_relative "lookups/media"
+require_relative "lookups/posts"
+require_relative "lookups/spaces"
+require_relative "lookups/trends"
+require_relative "lookups/users"
+
+module X
+  module Resources
+    # Lookups, searches, and collections, the modules of which X::Resources::API includes
+    #
+    # Internal to x-resources: a namespace of the modules API includes into a client, and not itself included, so that
+    # the modules it holds are not constants of the client, where the name of one, such as Media, would shadow a
+    # constant of the same name in a class that inherits from the client. Include API rather than any of them.
+    #
+    # @api private
+    module Lookups
+    end
+    private_constant :Lookups
+  end
+end

data/lib/x/resources/marshalling.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "includes"
+
+module X
+  module Resources
+    # The state of a resource Marshal and YAML write and read
+    #
+    # Internal to x-resources: the methods it gives a resource, marshal_dump, marshal_load, encode_with, and init_with,
+    # are public API, but the module is only how they are given, and which classes include it can change within 1.x.
+    #
+    # @api semipublic
+    module Marshalling
+      # The number of the format of the state Marshal writes, which every release of 1.x writes
+      #
+      # A later release of 1.x adds to the state only what an earlier one ignores, parts after those it reads and keys of a
+      # Hash it does not read, so that the state one release of 1.x writes is read by every other, earlier or later.
+      #
+      # @api private
+      MARSHAL_FORMAT = 1
+      # The name YAML writes each part of the state under, in the order Marshal writes them
+      # @api private
+      YAML_KEYS = %w[format attrs hydrated includes problems query].freeze
+      private_constant :MARSHAL_FORMAT, :YAML_KEYS
+
+      # The state Marshal writes, which leaves out the client
+      #
+      # The client is left out, since it holds credentials and a connection. What is written is plain data, led by
+      # the number of its format, so that a resource written by one release of 1.x is read by a later one: its
+      # attributes, whether it is hydrated, and, of the response it came from, the included objects it refers to, and
+      # those they refer to in turn, the problems about any of them, and the query, so that the references it
+      # resolves, and the problems it and they report, are what they were, while the rest of the response is left
+      # out, however many other resources it held.
+      #
+      # @api public
+      # @return [Array] the number of the format, then the state of the resource
+      # @example Cache a user
+      #   Rails.cache.write("user", user)
+      def marshal_dump
+        data, problems, query = includes.state_of([self]) # steep:ignore NoMethod
+        [MARSHAL_FORMAT, attrs, hydrated?, data, problems, query]
+      end
+
+      # Restore a resource Marshal read, which has no client and so makes no request
+      #
+      # What Marshal reads is a client-less resource that answers its readers, resolves the references its response
+      # included, and reports its problems, as the resource that was written did, and raises from a hydrate, refresh,
+      # or collection that would make a request. It is hydrated if it was, and the query of its request asks for every
+      # field this release requests, so that one written before a minor release added to the fields is not.
+      #
+      # @api public
+      # @param state [Array] the state Marshal wrote
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read a cached user
+      #   Marshal.load(Marshal.dump(user)).username # => "sferik"
+      def marshal_load(state)
+        format, attrs, hydrated, data, problems, query = state
+        raise UnsupportedFormat, "#{self.class} reads format #{MARSHAL_FORMAT} of Marshal, not #{format.inspect}" unless MARSHAL_FORMAT.eql?(format)
+
+        includes = Includes.new(data, problems:, query:)
+        setup(attrs, client: nil, hydrated: includes.hydrated_as_read?(self.class, hydrated), includes:) # steep:ignore NoMethod
+      end
+
+      # Write the state Marshal writes as YAML, which leaves out the client
+      #
+      # YAML reads no marshal_dump, and would write every instance variable, the client and its credentials among
+      # them, so a resource says how it is written: each part of the state Marshal writes, under its name.
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML writes the resource with
+      # @return [void]
+      # @example Write a user as YAML, as a queue writes the arguments of a job
+      #   YAML.dump(user)
+      def encode_with(coder) = YAML_KEYS.zip(marshal_dump) { |key, value| coder[key] = value }
+
+      # Restore a resource YAML read, as Marshal restores one
+      #
+      # It has no client, and so makes no request.
+      #
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML read the resource with
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read a user written as YAML
+      #   YAML.unsafe_load(YAML.dump(user)).username # => "sferik"
+      def init_with(coder) = marshal_load(coder.map.values_at(*YAML_KEYS))
+    end
+    private_constant :Marshalling
+  end
+end