Version 9.1.0

Author: bodrovis

.gitignore

@@ -10,4 +10,5 @@ measurement/*
 pkg/*
 .DS_Store
 .env
-demo.rb
+demo.rb
+.ruby-lsp

.rubocop.yml

@@ -20,6 +20,10 @@ Layout/LineLength:
   Exclude:
     - ./*.gemspec
 
+Metrics/ClassLength:
+  CountComments: false
+  Max: 120
+
 Metrics/MethodLength:
   CountComments: false
   Max: 10

docs/Gemfile

@@ -27,7 +27,7 @@ end
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
 # and associated library.
 install_if -> { RUBY_PLATFORM =~ /mingw|mswin|java/ } do
-  gem 'tzinfo', '~> 1.2'
+  gem 'tzinfo', '~> 2.0'
   gem 'tzinfo-data'
 end
 

docs/additional_info/changelog.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 9.1.0 (15-May-2024)
+
+* Add support for [cursor pagination](https://lokalise.github.io/ruby-lokalise-api/api/getting-started#cursor-pagination) for List keys and List translation endpoints:
+
+```ruby
+cursor_pagination_params = {
+  pagination: 'cursor',
+  cursor: 'eyIxIjozMTk3ODIzNzJ9', # The starting cursor. Optional, string
+  limit: 2 # The number of items to fetch. Optional, default is 100
+}
+
+keys = @client.keys '123abcdef.01', cursor_pagination_params
+
+keys.next_cursor? # => true
+keys.next_cursor # => 'eyIxIjozMTk3ODIzNzV9'
+
+# Request keys from the next cursor (returns `nil` if the next cursor is not available):
+keys_next_cursor = keys.load_next_cursor
+```
+
 ## 9.0.1 (13-Mar-2024)
 
 * Handle cases when server responds with non-JSON

docs/api/getting-started.md

@@ -138,6 +138,26 @@ first_translation = prev_page_translations.first # get first translation from th
 first_translation.translation # => 'Translation text'
 ```
 
+### Cursor pagination
+
+The [List Keys](https://developers.lokalise.com/reference/list-all-keys) and [List Translations](https://developers.lokalise.com/reference/list-all-translations) endpoints support cursor pagination, which is recommended for its faster performance compared to traditional "offset" pagination. By default, "offset" pagination is used, so you must explicitly set `pagination` to `"cursor"` to use cursor pagination.
+
+```ruby
+cursor_pagination_params = {
+  pagination: 'cursor',
+  cursor: 'eyIxIjozMTk3ODIzNzJ9', # The starting cursor. Optional, string
+  limit: 2 # The number of items to fetch. Optional, default is 100
+}
+
+keys = @client.keys '123abcdef.01', cursor_pagination_params
+
+keys.next_cursor? # => true
+keys.next_cursor # => 'eyIxIjozMTk3ODIzNzV9'
+
+# Request keys from the next cursor (returns `nil` if the next cursor is not available):
+keys_next_cursor = keys.load_next_cursor
+```
+
 ## Branching
 
 If you are using [project branching feature](https://docs.lokalise.com/en/articles/3391861-project-branching), simply add branch name separated by semicolon to your project ID in any endpoint to access the branch. For example, in order to access `new-feature` branch for the project with an id `123abcdef.01`:

docs/api/keys.md

@@ -8,11 +8,13 @@
 @client.keys(project_id, params = {})   # Input:
                                         ## project_id (string, required)
                                         ## params (hash)
-                                        ### :page and :limit
+                                        ### pagination and cursor-related params
                                         # Output:
                                         ## Collection of keys available in the given project
 ```
 
+**This endpoint also supports cursor pagination which is now a recommended approach, especially for fetching large amounts of data. Please [learn more in the Pagination docs](https://lokalise.github.io/ruby-lokalise-api/api/getting-started#cursor-pagination).**
+
 For example:
 
 ```ruby

docs/api/translations.md

@@ -9,11 +9,12 @@
                                                 ## project_id (string, required)
                                                 ## params (hash)
                                                 ### Find full list in the docs
-                                                ### :page and :limit
                                                 # Output:
                                                 ## Collection of translations for the project
 ```
 
+**This endpoint also supports cursor pagination which is now a recommended approach, especially for fetching large amounts of data. Please [learn more in the Pagination docs](https://lokalise.github.io/ruby-lokalise-api/api/getting-started#cursor-pagination).**
+
 For example:
 
 ```ruby

lib/ruby_lokalise_api/collections/base.rb

@@ -18,7 +18,7 @@ class Base
       def_delegators :collection, :[], :last, :each
 
       attr_reader :total_pages, :total_results, :results_per_page, :current_page,
-                  :collection
+                  :collection, :next_cursor
 
       def initialize(response)
         @self_endpoint = response.endpoint
@@ -32,9 +32,25 @@ def initialize(response)
       def next_page
         return nil if last_page?
 
+        override_params = { page: current_page + 1 }
+
         self.class.new(
           reinit_endpoint(
-            override_req_params: { page: current_page + 1 }
+            override_req_params: override_params
+          ).do_get
+        )
+      end
+
+      # Tries to fetch the next cursor for paginated collection
+      # Returns a new collection or nil if the next cursor is not available
+      def load_next_cursor
+        return nil unless next_cursor?
+
+        override_params = { cursor: next_cursor }
+
+        self.class.new(
+          reinit_endpoint(
+            override_req_params: override_params
           ).do_get
         )
       end
@@ -75,6 +91,12 @@ def first_page?
         !prev_page?
       end
 
+      # Checks whether the next cursor is available
+      # @return [Boolean]
+      def next_cursor?
+        !next_cursor.nil? && next_cursor != ''
+      end
+
       private
 
       # This method is utilized to recreate an endpoint for the current collection
@@ -89,14 +111,17 @@ def populate_common_attrs_from(response)
           instance_variable_set :"@#{attrib}", response.content[attrib]
         end
 
-        headers = response.headers
+        extract_common_from_headers(response.headers)
+      end
 
+      def extract_common_from_headers(headers)
         return unless headers.any?
 
-        @total_results = headers[:'x-pagination-total-count']
-        @total_pages = headers[:'x-pagination-page-count']
-        @results_per_page = headers[:'x-pagination-limit']
-        @current_page = headers[:'x-pagination-page']
+        @total_results = headers[:'x-pagination-total-count'].to_i
+        @total_pages = headers[:'x-pagination-page-count'].to_i
+        @results_per_page = headers[:'x-pagination-limit'].to_i
+        @current_page = headers[:'x-pagination-page'].to_i
+        @next_cursor = headers[:'x-pagination-next-cursor']
       end
 
       def produce_collection_from(response)

lib/ruby_lokalise_api/response.rb

@@ -5,7 +5,7 @@ module RubyLokaliseApi
   class Response
     # Lokalise returns pagination info in special headers
     PAGINATION_HEADERS = %w[x-pagination-total-count x-pagination-page-count x-pagination-limit
-                            x-pagination-page].freeze
+                            x-pagination-page x-pagination-next-cursor].freeze
 
     attr_reader :content, :endpoint, :headers
 
@@ -43,8 +43,7 @@ def extract_headers_from(raw_headers)
       raw_headers.
         to_h.
         keep_if { |header, _value| pagination_headers.include?(header) }.
-        transform_keys(&:to_sym).
-        transform_values(&:to_i)
+        transform_keys(&:to_sym)
     end
   end
 end

lib/ruby_lokalise_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyLokaliseApi
-  VERSION = '9.0.1'
+  VERSION = '9.1.0'
 end