wagoe.platform.core.pagination.pagination — com.wagoe/wagoe-platform 1.0.0-beta-5

Pure functions for pagination logic.

This namespace provides pure functional implementations for pagination calculations, following the Functional Core pattern. All functions are deterministic and side-effect free.

Supports:

• Offset-based pagination (simple, familiar)
• Cursor-based pagination (high performance, stable results)
• Parameter validation
• Metadata calculation

Pure: All functions return data, no side effects.

add-api-metadata clj

(add-api-metadata version timestamp)

Add API metadata to response.

Args: version - API version (e.g., :v1) timestamp - ISO 8601 timestamp string

Returns: Metadata map

Pure: true

calculate-cursor-pagination clj

(calculate-cursor-pagination _items limit next-cursor prev-cursor)

Calculate cursor pagination metadata.

Args: items - Current page items limit - Items per page next-cursor - Cursor for next page (optional) prev-cursor - Cursor for previous page (optional)

Returns: {:type "cursor" :limit int :next-cursor string or nil :prev-cursor string or nil :has-next? bool :has-prev? bool}

Pure: true

calculate-next-offset clj

(calculate-next-offset current-offset limit total)

Calculate next page offset.

Args: current-offset - Current offset limit - Items per page total - Total items (optional, for bounds checking)

Returns: Next offset, or nil if at end

Pure: true

calculate-offset-pagination clj

(calculate-offset-pagination total offset limit)

Calculate offset pagination metadata.

Args: total - Total number of items in collection offset - Starting position (0-based) limit - Number of items per page

Returns: {:type "offset" :total int - Total items :offset int - Current offset :limit int - Items per page :has-next? bool - More items available :has-prev? bool - Previous page available :page int - Current page (1-based) :pages int - Total pages}

Examples: (calculate-offset-pagination 100 0 20) => {:type "offset" :total 100 :offset 0 :limit 20 :has-next? true :has-prev? false :page 1 :pages 5}

(calculate-offset-pagination 100 80 20) => {:type "offset" :total 100 :offset 80 :limit 20 :has-next? false :has-prev? true :page 5 :pages 5}

Pure: true

calculate-prev-offset clj

(calculate-prev-offset current-offset limit)

Calculate previous page offset.

Args: current-offset - Current offset limit - Items per page

Returns: Previous offset, or nil if at beginning

Pure: true

create-paginated-response clj

(create-paginated-response data pagination meta)

Create standardized paginated response envelope.

Args: data - Collection of items pagination - Pagination metadata meta - Optional additional metadata

Returns: {:data collection :pagination metadata :meta metadata}

Pure: true

extract-cursor-value clj

(extract-cursor-value item sort-key)

Extract cursor value from item based on sort key.

Args: item - Item to extract cursor from sort-key - Keyword for sort field (e.g., :created-at, :id)

Returns: {:id value :sort-value value}

Examples: (extract-cursor-value {:id 123 :created-at "2024-01-01"} :created-at) => {:id 123 :sort-value "2024-01-01"}

Pure: true

parse-limit clj

(parse-limit limit-value default-limit)

Parse limit parameter from string or integer.

Args: limit-value - String, integer, or nil default-limit - Default if not provided

Returns: Integer limit value, or default

Pure: true

parse-offset clj

(parse-offset offset-value)

Parse offset parameter from string or integer.

Args: offset-value - String, integer, or nil

Returns: Integer offset value, or 0

Pure: true

parse-sort clj

(parse-sort sort-value)

Parse sort parameter into field and direction.

Args: sort-value - String like "created_at" or "-created_at" (desc)

Returns: {:field keyword :direction :asc or :desc}

Examples: (parse-sort "created_at") => {:field :created-at :direction :asc} (parse-sort "-created_at") => {:field :created-at :direction :desc} (parse-sort nil) => {:field :created-at :direction :desc}

Pure: true

prepare-link-data clj

(prepare-link-data base-path pagination query-params)

Prepare data for link URL construction.

This is a pure function that prepares the data structure needed for link generation. The actual URL construction happens in the shell layer.

Args: base-path - Base path (e.g., "/api/v1/users") pagination - Pagination metadata query-params - Additional query parameters

Returns: {:first {:path string :params map} :last {:path string :params map} or nil :next {:path string :params map} or nil :prev {:path string :params map} or nil}

Pure: true

validate-pagination-params clj

(validate-pagination-params params config)

Validate pagination parameters.

Args: params - Map with :limit, :offset, :cursor config - Configuration with :default-limit, :max-limit

Returns: {:valid? bool :errors map - Field name to error messages :params map - Normalized parameters}

Examples: (validate-pagination-params {:limit 50} {:default-limit 20 :max-limit 100}) => {:valid? true :errors {} :params {:limit 50 :offset 0}}

(validate-pagination-params {:limit 200} {:max-limit 100}) => {:valid? false :errors {:limit "Must be at most 100"} ...}

Pure: true

validate-sort-field clj

(validate-sort-field sort-field allowed-fields)

Validate sort field against allowed fields.

Args: sort-field - Keyword field name allowed-fields - Set of allowed keywords

Returns: {:valid? bool :error string or nil}

Pure: true