toc_doc 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36c32de39cc1eed0396372360e37b86d7df01e342926c32ab03aa450db500ff9
-  data.tar.gz: 578e0b0c633708c5c8adc7f3e8b0212e563ca7eb07c9e7b73b52d72196b7f652
+  metadata.gz: 72ce333b7f46666dc6109150032a053014153937a65f89d629d1a686216d52b3
+  data.tar.gz: 064462c8ae43a562a07b5e4f9f36aff3dc1b37f15444f3e912b04b61ce2e506d
 SHA512:
-  metadata.gz: b120c55bf6b52c77b78c609867385150647fb0163d32abd449da8a53a4851939f0053caa3983784b80826be6bf4a6097da7084b0580f1d30d63a6066c5c61c7e
-  data.tar.gz: b463ad3fbc58cbd14101e5d8c1bffa37bacfda4373fd7a5c821ae2666d9b0ce839506e5ca97a2926389398387e900e26aac5cc977e036162d55e497d46de27d1
+  metadata.gz: b5750b8a84a14ba7a9144ead48313f8db74829de9f4bddaf58930ebaf1606400dc4cff0a1110cbb587999b22bf0efff490beaa3710fc21c96dbd402d4068c069
+  data.tar.gz: 563244b90ad4a8418d7348e88bb1c408955285574a2a5d7efbcac02c9e311b70410f868fbd4777b63a163ce90f525075361ec457b3618537a44ccce133fd33e4

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [1.9.0] - 2026-04-06
+
+### Added
+
+- **`TocDoc::Availability::Collection#availabilities`** — new public method returning all `TocDoc::Availability` instances that have at least one slot; results are memoized and invalidated by `#merge_page!`
+- **`TocDoc::Availability::Collection#all`** — alias for `#availabilities`
+- **`TocDoc::Availability::Collection#slots`** — returns all individual slots across every availability in the collection as `Array<DateTime>`
+
+### Changed
+
+- **`TocDoc::Availability::Collection#fetch_next_page`** renamed to **`#load_next!`** for a more idiomatic, mutation-signalling name
+
 ## [1.8.0] - 2026-04-05
 
 ### Added

data/README.md

@@ -306,10 +306,12 @@ Implements `Enumerable`, yielding `TocDoc::Availability` instances that have at
 |---|---|---|
 | `#total` | `Integer` | Total number of available slots across all dates. |
 | `#next_slot` | `String \| nil` | ISO 8601 datetime of the nearest available slot. `nil` when none remain. |
+| `#availabilities` | `Array<TocDoc::Availability>` | All entries that have at least one slot. Aliased as `#all`. Memoized; invalidated by `#merge_page!`. |
+| `#slots` | `Array<DateTime>` | All individual slots across every availability in the collection. |
 | `#each` | — | Yields each `TocDoc::Availability` that has at least one slot (excludes empty-slot dates). |
 | `#raw_availabilities` | `Array<TocDoc::Availability>` | All date entries, including those with no slots. |
 | `#more?` | `Boolean` | `true` when the API has indicated further pages exist (`next_slot` is present). |
-| `#fetch_next_page` | `self` | Fetches the next page and merges it into this collection. Raises `StopIteration` when `#more?` is `false`. Requires a client (i.e. built via `Availability.where`). |
+| `#load_next!` | `self` | Fetches the next window and merges it into this collection. Raises `StopIteration` when `#more?` is `false`. Requires a client (i.e. built via `Availability.where`). |
 | `#to_h` | `Hash` | Plain-hash representation (only dates with slots in the `availabilities` key). |
 
 ### `TocDoc::Availability`
@@ -464,10 +466,10 @@ TocDoc.configure { |c| c.pagination_depth = 3 }
 # → up to 3 next_slot hops per Availability.where call
 ```
 
-### On-demand pagination with `#fetch_next_page`
+### On-demand pagination with `#load_next!`
 
-After the initial call, check `#more?` and call `#fetch_next_page` to load
-additional pages one at a time:
+After the initial call, check `#more?` and call `#load_next!` to load
+additional windows one at a time:
 
 ```ruby
 collection = TocDoc::Availability.where(
@@ -477,7 +479,7 @@ collection = TocDoc::Availability.where(
 )
 
 while collection.more?
-  collection.fetch_next_page
+  collection.load_next!
 end
 
 collection.total  # slots across all fetched pages

data/TODO.md

@@ -3,7 +3,7 @@
 [POTENTIAL_ENDPOINTS][POTENTIAL_ENDPOINTS.md]
 
 
-## 1.9 — Service Layer rework
+## Service Layer rework
 
 - [ ] `TocDoc::Services::Availabilities` — extract from `Availability.where`
 - [ ] `TocDoc::Services::Profiles` — extract from `Profile.find`
@@ -12,14 +12,14 @@
 - [ ] Update top-level shortcuts to delegate to services
 - [ ] Deprecation on old model-level finders
 
-## 2.0 — Breaking Changes
+## Breaking Changes
 
 - [ ] Remove deprecated model-level finders
 - [ ] `Place#coordinates` as `Data.define(:latitude, :longitude)`
 - [ ] Integration smoke test suite (gated by ENV, weekly CI cron)
 - [ ] Remove unused HTTP verbs from `Connection` (if auth doesn't ship)
 
-# ???
+# Misc.
 
 - [ ] Figure what is `organization_statuses` in the autocomplete endpoint and what to do with it.
 - [ ] Authentication module

data/lib/toc_doc/core/version.rb

@@ -4,5 +4,5 @@ module TocDoc
   # The current version of the TocDoc gem.
   #
   # @return [String]
-  VERSION = '1.8.0'
+  VERSION = '1.9.0'
 end

data/lib/toc_doc/models/availability/collection.rb

@@ -24,7 +24,7 @@ module TocDoc
       # @param query [Hash] original query params (used to build next-page requests)
       # @param path [String] API path for subsequent requests
       # @param client [TocDoc::Client, nil] client used to fetch additional pages
-      #   via {#fetch_next_page}; +nil+ disables {#fetch_next_page}
+      #   via {#load_next!}; +nil+ disables {#load_next!}
       def initialize(data, query: {}, path: '/availabilities.json', client: nil)
         @data = data.dup
         @query = query
@@ -32,12 +32,32 @@ module TocDoc
         @client = client
       end
 
+      # All {TocDoc::Availability} instances that have at least one slot.
+      #
+      # Results are memoized and invalidated by {#merge_page!}.
+      #
+      # @return [Array<TocDoc::Availability>]
+      def availabilities
+        @availabilities ||= Array(@data['availabilities'])
+                            .select { |entry| Array(entry['slots']).any? }
+                            .map { |entry| TocDoc::Availability.new(entry) }
+      end
+
+      alias all availabilities
+
+      # All individual slots across every availability in the collection.
+      #
+      # @return [Array<DateTime>]
+      def slots
+        availabilities.flat_map(&:slots)
+      end
+
       # Iterates over {TocDoc::Availability} instances that have at least one slot.
       #
       # @yieldparam availability [TocDoc::Availability]
       # @return [Enumerator] if no block given
       def each(&)
-        filtered_entries.each(&)
+        availabilities.each(&)
       end
 
       # The total number of available slots in the collection.
@@ -73,7 +93,7 @@ module TocDoc
         !!@data['next_slot']
       end
 
-      # Fetches the next page of availabilities and merges it into this collection.
+      # Fetches the next window of availabilities and merges it into this collection.
       #
       # Uses the +next_slot+ date from the API response as the +start_date+ for
       # the follow-up request.
@@ -83,8 +103,8 @@ module TocDoc
       # @return [self]
       #
       # @example
-      #   collection.fetch_next_page if collection.more?
-      def fetch_next_page
+      #   collection.load_next! if collection.more?
+      def load_next!
         raise TocDoc::Error, 'No client available for pagination' unless @client
         raise StopIteration, 'No more pages available' unless more?
 
@@ -110,7 +130,7 @@ module TocDoc
       #
       # @return [Hash{String => Object}]
       def to_h
-        @data.merge('availabilities' => filtered_entries.map(&:to_h))
+        @data.merge('availabilities' => availabilities.map(&:to_h))
       end
 
       # Fetches the next window of availabilities (starting the day after the
@@ -121,17 +141,9 @@ module TocDoc
       def merge_page!(page_data)
         @data['availabilities'] = @data.fetch('availabilities', []) + page_data.fetch('availabilities', [])
         @data['total']          = @data.fetch('total', 0) + page_data.fetch('total', 0)
-        @filtered_entries = nil
+        @availabilities = nil
         self
       end
-
-      private
-
-      def filtered_entries
-        @filtered_entries ||= Array(@data['availabilities'])
-                              .select { |entry| Array(entry['slots']).any? }
-                              .map { |entry| TocDoc::Availability.new(entry) }
-      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toc_doc
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - 01max