paged_groups 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cb8ac318e3df020ef112bcfd9a44fef6883519682be6501de014e745148b4046
+  data.tar.gz: 7d69dea71a15bf728052cdfe80341e24b2ac32b0bc93bf5ab3f3b0891bd66b4f
+SHA512:
+  metadata.gz: f60342818d52bce7432752e19d852f47a8cb28ca2a9d5216b39175e1ba47e9f71b9f2a8bb970751cc59a162c3d6af140dce2e95bfed5fcea53605b1b2b0e0c09
+  data.tar.gz: 86a0b7432ee2cefb13aad7b9e9d13ca1e2d35f60e93ebc58b798a2700816810be09c5b5580f26c10a6144664483aea9877108f1dea44983a20de647dc1c05c95

data/.editorconfig

@@ -0,0 +1,8 @@
+# See http://editorconfig.org/
+
+[*]
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+end_of_line = lf

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+*.gem
+/tmp

data/.rubocop.yml

@@ -0,0 +1,8 @@
+Metrics/LineLength:
+  Max: 100
+
+Metrics/BlockLength:
+  ExcludedMethods: ['it', 'describe', 'context', 'let', 'specify']
+
+AllCops:
+  TargetRubyVersion: 2.3

data/.ruby-version

@@ -0,0 +1 @@
+2.6.0

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+# Build on the latest stable of all supported Rubies (https://www.ruby-lang.org/en/downloads/):
+- 2.3.8
+- 2.4.5
+- 2.5.3
+- 2.6.0
+cache: bundler
+script:
+- bundle exec rubocop
+- bundle exec rspec

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 1.0.0 (January 26th, 2019)
+
+Initial Release

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,87 @@
+PATH
+  remote: .
+  specs:
+    paged_groups (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    ffi (1.9.25)
+    formatador (0.2.5)
+    guard (2.15.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    jaro_winkler (1.5.1)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.13)
+    method_source (0.9.2)
+    nenv (0.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parallel (1.12.1)
+    parser (2.5.3.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rainbow (3.0.0)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.59.2)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.10.0)
+    ruby_dep (1.5.0)
+    shellany (0.0.1)
+    thor (0.20.3)
+    unicode-display_width (1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard-rspec (~> 4.7)
+  paged_groups!
+  rspec (~> 3.8)
+  rubocop (~> 0.59)
+
+BUNDLED WITH
+   1.17.3

data/Guardfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018 Blue Marble Payroll, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# paged_groups
+
+[![Build Status](https://travis-ci.org/bluemarblepayroll/paged_groups.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/paged_groups)
+
+Imagine a two-dimensional data set (first dimension being group and second dimension being record) for which you wanted to page with the following rules:
+
+1. Each page should roughly has the same number of records ([greedy](https://en.wikipedia.org/wiki/Greedy_algorithm))
+2. Each group should not be split between pages ([atomic](https://en.wikipedia.org/wiki/Atomicity_(database_systems)))
+
+This library helps you page grouped-data when the grouped data can have different sizes. It provides a builder that understands how to split pages in a fashion where each page tries to conform to a maximum page size but also ensures groups are not split up.
+
+## Installation
+
+To install through Rubygems:
+
+````
+gem install install paged_groups
+````
+
+You can also add this to your Gemfile:
+
+````
+bundle add paged_groups
+````
+
+## Examples
+
+### Standard Use-Case
+
+Here is an example data set containing groups with variable number of records:
+
+````ruby
+data = [
+  [
+    { id: 1, name: 'Jordan' },
+    { id: 2, name: 'Pippen' },
+    { id: 3, name: 'Rodman' },
+    { id: 4, name: 'Harper' },
+    { id: 5, name: 'Longley' }
+  ],
+  [
+    { id: 6, name: 'Kukoc' }
+  ],
+  [
+    { id: 7, name: 'Kerr' }
+  ],
+  [
+    { id: 8, name: 'Buechler' }
+  ],
+  [
+    { id: 9, name: 'Wennington' },
+    { id: 10, name: 'Simpkins' }
+  ],
+  [
+    { id: 11, name: 'Caffey' },
+    { id: 12, name: 'Edwards' },
+    { id: 13, name: 'Salley' }
+  ]
+]
+````
+
+Let's use max page size of three for this example.  In the real-world a max page size of three is most likely too small but it fits our example data set above for illustration purpose; you should be able to extrapolate this out with larger sets and larger max page sizes.  To page this set we would execute:
+
+````ruby
+pages = PagedGroups.builder(page_size: 3).add(*data).all
+````
+
+*Note:* We are using the splat (asterisk) operator to indicate each group is an argument.
+
+our ````pages```` variable should now contain a two-dimensional array where dimension one is page and dimension two is record and would be:
+
+````ruby
+[
+  [
+    { id: 1, name: 'Jordan' },
+    { id: 2, name: 'Pippen' },
+    { id: 3, name: 'Rodman' },
+    { id: 4, name: 'Harper' },
+    { id: 5, name: 'Longley' }
+  ],
+  [
+    { id: 6, name: 'Kukoc' },
+    { id: 7, name: 'Kerr' },
+    { id: 8, name: 'Buechler' }
+  ],
+  [
+    { id: 9, name: 'Wennington' },
+    { id: 10, name: 'Simpkins' }
+  ],
+  [
+    { id: 11, name: 'Caffey' },
+    { id: 12, name: 'Edwards' },
+    { id: 13, name: 'Salley' }
+  ]
+]
+````
+
+Notice how each group was kept atomic while each page was tried to be kept as close to the max page size as possible.
+
+### Spacing Customization
+
+There may be merit in placing *separator* record in between groups in the same page.  This separate record can act as a spacer.  You can specify this spacer row in the builder's constructor:
+
+````ruby
+pages = PagedGroups.builder(page_size: 3, space: true, spacer: { id: nil, name: '' })
+                   .add(*data)
+                   .all
+````
+
+*Note:* ````spacer```` (boolean) argument is split from ````space```` (object) to allow for spacer to be anything (even false or nil.)
+
+Now, our resulting pages would become:
+
+````ruby
+[
+  [
+    { id: 1, name: 'Jordan' },
+    { id: 2, name: 'Pippen' },
+    { id: 3, name: 'Rodman' },
+    { id: 4, name: 'Harper' },
+    { id: 5, name: 'Longley' }
+  ],
+  [
+    { id: 6, name: 'Kukoc' },
+    { id: nil, name: '' },
+    { id: 7, name: 'Kerr' }
+  ],
+  [
+    { id: 8, name: 'Buechler' },
+    { id: nil, name: '' },
+    { id: 9, name: 'Wennington' },
+    { id: 10, name: 'Simpkins' }
+  ],
+  [
+    { id: 11, name: 'Caffey' },
+    { id: 12, name: 'Edwards' },
+    { id: 13, name: 'Salley' }
+  ]
+]
+````
+
+
+### Forcing Same Page
+
+Another customization that may come in handy is the ability to force-add groups to the current page.  For example, say we wanted to add another group to our initial data set, but we want it to end up on the same page as the last records:
+
+````ruby
+other_data = [
+  [
+    { id: 14, name: 'Jackson' },
+    { id: 14, name: 'Winters' }
+  ]
+]
+pages = PagedGroups.builder(page_size: 3, space: true, spacer: { id: nil, name: '' })
+                   .add(*data)
+                   .add(*other_data, force: true)
+                   .all
+````
+
+*Note:* #add has a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface) and can be chained as illustrated above.
+
+Now the result pages would be:
+
+````ruby
+[
+  [
+    { id: 1, name: 'Jordan' },
+    { id: 2, name: 'Pippen' },
+    { id: 3, name: 'Rodman' },
+    { id: 4, name: 'Harper' },
+    { id: 5, name: 'Longley' }
+  ],
+  [
+    { id: 6, name: 'Kukoc' },
+    { id: nil, name: '' },
+    { id: 7, name: 'Kerr' }
+  ],
+  [
+    { id: 8, name: 'Buechler' },
+    { id: nil, name: '' },
+    { id: 9, name: 'Wennington' },
+    { id: 10, name: 'Simpkins' }
+  ],
+  [
+    { id: 11, name: 'Caffey' },
+    { id: 12, name: 'Edwards' },
+    { id: 13, name: 'Salley' },
+    { id: nil, name: '' },
+    { id: 14, name: 'Jackson' },
+    { id: 14, name: 'Winters' }
+  ]
+]
+````
+
+## Contributing
+
+### Development Environment Configuration
+
+Basic steps to take to get this repository compiling:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check paged_groups.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/paged_groups.git)
+4. Navigate to the root folder (cd paged_groups)
+5. Install dependencies (bundle)
+
+### Running Tests
+
+To execute the test suite run:
+
+````
+bundle exec rspec spec --format documentation
+````
+
+Alternatively, you can have Guard watch for changes:
+
+````
+bundle exec guard
+````
+
+Also, do not forget to run Rubocop:
+
+````
+bundle exec rubocop
+````
+
+### Publishing
+
+Note: ensure you have proper authorization before trying to publish new versions.
+
+After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:
+
+1. Merge Pull Request into master
+2. Update [lib/paged_groups/version.rb](https://github.com/bluemarblepayroll/paged_groups/blob/master/lib/paged_groups/version.rb) [version number](https://semver.org/)
+3. Bundle
+4. Update CHANGELOG.md
+5. Commit & Push master to remote and ensure CI builds master successfully
+6. Build the project locally: `gem build paged_groups`
+7. Publish package to NPM: `gem push paged_groups-X.gem` where X is the version to push
+8. Tag master with new version: `git tag <version>`
+9. Push tags remotely: `git push origin --tags`
+
+## License
+
+This project is MIT Licensed.

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'paged_groups'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/lib/paged_groups.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'paged_groups/paged_groups'

data/lib/paged_groups/builder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module PagedGroups
+  # This is the Public API for this library.
+  class Builder
+    DEFAULT_PAGE_SIZE = 50
+
+    attr_reader :page_size,
+                :page_count,
+                :row_count,
+                :space,
+                :spacer
+
+    def initialize(page_size: DEFAULT_PAGE_SIZE, space: false, spacer: nil)
+      @page_size  = page_size ? page_size.to_i : DEFAULT_PAGE_SIZE
+      @space      = space || false
+      @spacer     = spacer
+
+      clear
+    end
+
+    def add(*groups, force: false)
+      dirty!
+
+      groups.each { |group| insert(Array(group), force: force) }
+
+      self
+    end
+
+    def clear
+      dirty!
+
+      @pages        = []
+      @page_count   = 0
+      @current_page = []
+      @row_count    = 0
+    end
+
+    def all
+      return @all if @all
+
+      @all = top? ? @pages : @pages + [@current_page]
+    end
+    alias to_a all
+
+    def to_s
+      "[#{self.class.name}] Page Count: #{page_count}, Row Count: #{row_count}"
+    end
+
+    private
+
+    def insert(rows, force: false)
+      cut! if start_new_page?(rows) && !force
+
+      space_if_needed
+
+      @current_page += rows
+
+      @row_count += rows.length
+
+      self
+    end
+
+    def not_top?
+      !top?
+    end
+
+    def top?
+      @current_page.empty?
+    end
+
+    def dirty!
+      @all = nil
+    end
+
+    def cut!
+      @page_count += 1
+      @pages << @current_page
+      @current_page = []
+
+      nil
+    end
+
+    def space_if_needed
+      @current_page << spacer if space && not_top?
+
+      nil
+    end
+
+    def start_new_page?(next_items)
+      proposed_current_page_length = @current_page.length + next_items.length
+
+      not_top? && proposed_current_page_length > page_size
+    end
+
+    def end_of_current_page?
+      @current_page.length >= page_size
+    end
+  end
+end

data/lib/paged_groups/paged_groups.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'builder'
+
+# Top-level namespace for primary public API.
+module PagedGroups
+  class << self
+    # This is syntactic sugar and is equivalent to: PagedGroups::Builder.new(args)
+    # Check the constructor signature of PagedGroups::Builder for argument definition.
+    def builder(*args)
+      ::PagedGroups::Builder.new(*args)
+    end
+  end
+end

data/lib/paged_groups/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module PagedGroups
+  VERSION = '1.0.0'
+end

data/paged_groups.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require './lib/paged_groups/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'paged_groups'
+  s.version     = PagedGroups::VERSION
+  s.summary     = 'Create an evenly paged dataset of un-evenly sized groups'
+
+  s.description = <<-DESCRIPTION
+    This library helps you page grouped-data when the grouped data can have different sizes.
+    It provides a builder that understands how to split pages in a fashion where each page tries to
+    conform to a maximum page size (greedy) but also ensures groups are not split up (atomic.)
+  DESCRIPTION
+
+  s.authors     = ['Matthew Ruggio']
+  s.email       = ['mruggio@bluemarblepayroll.com']
+  s.files       = `git ls-files`.split("\n")
+  s.test_files  = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.homepage    = 'https://github.com/bluemarblepayroll/paged_groups'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 2.3.8'
+
+  s.add_development_dependency('guard-rspec', '~>4.7')
+  s.add_development_dependency('rspec', '~> 3.8')
+  s.add_development_dependency('rubocop', '~> 0.59')
+end

data/spec/paged_groups/builder_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require './spec/spec_helper'
+
+describe ::PagedGroups::Builder do
+  let(:page_size) { 44 }
+
+  let(:spacer) { 'SPACER' }
+
+  let(:page_builder) do
+    ::PagedGroups::Builder.new(page_size: page_size, spacer: spacer, space: true)
+  end
+
+  let(:hundred_rows) { Array.new(100) }
+
+  let(:twenty_rows) { Array.new(20) }
+
+  subject { page_builder }
+
+  it { expect(page_builder.page_size).to eq(page_size) }
+
+  describe '#add and #all' do
+    it 'should page groups' do
+      page_builder.add(hundred_rows)
+
+      expect(page_builder.all.length).to eq(1)
+
+      page_builder.add(twenty_rows)
+      page_builder.add(twenty_rows)
+
+      expect(page_builder.all.length).to eq(2)
+
+      page_builder.add(twenty_rows)
+
+      expect(page_builder.all.length).to eq(3)
+    end
+
+    it 'should force add and space' do
+      page_builder.add(hundred_rows)
+
+      expect(page_builder.all.length).to eq(1)
+      expect(page_builder.all.first.length).to eq(100)
+
+      page_builder.add(twenty_rows, force: true)
+      page_builder.add(twenty_rows, force: true)
+
+      expect(page_builder.all.length).to eq(1)
+      expect(page_builder.all.first.length).to eq(100 + 20 * 2 + 2)
+
+      first_spacer_index = 100
+      second_spacer_index = 100 + 20 + 1
+
+      expect(page_builder.all.first[first_spacer_index]).to eq(spacer)
+      expect(page_builder.all.first[second_spacer_index]).to eq(spacer)
+    end
+  end
+end

data/spec/paged_groups/paged_groups_spec.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require './spec/spec_helper'
+
+describe ::PagedGroups do
+  describe 'README examples' do
+    let(:data) do
+      [
+        [
+          { id: 1, name: 'Jordan' },
+          { id: 2, name: 'Pippen' },
+          { id: 3, name: 'Rodman' },
+          { id: 4, name: 'Harper' },
+          { id: 5, name: 'Longley' }
+        ],
+        [
+          { id: 6, name: 'Kukoc' }
+        ],
+        [
+          { id: 7, name: 'Kerr' }
+        ],
+        [
+          { id: 8, name: 'Buechler' }
+        ],
+        [
+          { id: 9, name: 'Wennington' },
+          { id: 10, name: 'Simpkins' }
+        ],
+        [
+          { id: 11, name: 'Caffey' },
+          { id: 12, name: 'Edwards' },
+          { id: 13, name: 'Salley' }
+        ]
+      ]
+    end
+
+    let(:page_size) { 3 }
+
+    let(:spacer) { { id: nil, name: '' } }
+
+    specify 'Standard use-case example works as advertised' do
+      pages = PagedGroups.builder(page_size: page_size).add(*data).all
+
+      expected_pages = [
+        [
+          { id: 1, name: 'Jordan' },
+          { id: 2, name: 'Pippen' },
+          { id: 3, name: 'Rodman' },
+          { id: 4, name: 'Harper' },
+          { id: 5, name: 'Longley' }
+        ],
+        [
+          { id: 6, name: 'Kukoc' },
+          { id: 7, name: 'Kerr' },
+          { id: 8, name: 'Buechler' }
+        ],
+        [
+          { id: 9, name: 'Wennington' },
+          { id: 10, name: 'Simpkins' }
+        ],
+        [
+          { id: 11, name: 'Caffey' },
+          { id: 12, name: 'Edwards' },
+          { id: 13, name: 'Salley' }
+        ]
+      ]
+
+      expect(pages).to eq(expected_pages)
+    end
+
+    specify 'Spacing customization example works as advertised' do
+      pages = PagedGroups.builder(page_size: page_size, space: true, spacer: spacer)
+                         .add(*data)
+                         .all
+
+      expected_pages = [
+        [
+          { id: 1, name: 'Jordan' },
+          { id: 2, name: 'Pippen' },
+          { id: 3, name: 'Rodman' },
+          { id: 4, name: 'Harper' },
+          { id: 5, name: 'Longley' }
+        ],
+        [
+          { id: 6, name: 'Kukoc' },
+          { id: nil, name: '' },
+          { id: 7, name: 'Kerr' }
+        ],
+        [
+          { id: 8, name: 'Buechler' },
+          { id: nil, name: '' },
+          { id: 9, name: 'Wennington' },
+          { id: 10, name: 'Simpkins' }
+        ],
+        [
+          { id: 11, name: 'Caffey' },
+          { id: 12, name: 'Edwards' },
+          { id: 13, name: 'Salley' }
+        ]
+      ]
+
+      expect(pages).to eq(expected_pages)
+    end
+
+    specify 'Forcing same page example works as advertised' do
+      other_data = [
+        [
+          { id: 14, name: 'Jackson' },
+          { id: 14, name: 'Winters' }
+        ]
+      ]
+
+      pages = PagedGroups.builder(page_size: page_size, space: true, spacer: spacer)
+                         .add(*data)
+                         .add(*other_data, force: true)
+                         .all
+
+      expected_pages = [
+        [
+          { id: 1, name: 'Jordan' },
+          { id: 2, name: 'Pippen' },
+          { id: 3, name: 'Rodman' },
+          { id: 4, name: 'Harper' },
+          { id: 5, name: 'Longley' }
+        ],
+        [
+          { id: 6, name: 'Kukoc' },
+          { id: nil, name: '' },
+          { id: 7, name: 'Kerr' }
+        ],
+        [
+          { id: 8, name: 'Buechler' },
+          { id: nil, name: '' },
+          { id: 9, name: 'Wennington' },
+          { id: 10, name: 'Simpkins' }
+        ],
+        [
+          { id: 11, name: 'Caffey' },
+          { id: 12, name: 'Edwards' },
+          { id: 13, name: 'Salley' },
+          { id: nil, name: '' },
+          { id: 14, name: 'Jackson' },
+          { id: 14, name: 'Winters' }
+        ]
+      ]
+
+      expect(pages).to eq(expected_pages)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require './lib/paged_groups'

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: paged_groups
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Matthew Ruggio
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.59'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.59'
+description: |2
+      This library helps you page grouped-data when the grouped data can have different sizes.
+      It provides a builder that understands how to split pages in a fashion where each page tries to
+      conform to a maximum page size (greedy) but also ensures groups are not split up (atomic.)
+email:
+- mruggio@bluemarblepayroll.com
+executables:
+- console
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- LICENSE
+- README.md
+- bin/console
+- lib/paged_groups.rb
+- lib/paged_groups/builder.rb
+- lib/paged_groups/paged_groups.rb
+- lib/paged_groups/version.rb
+- paged_groups.gemspec
+- spec/paged_groups/builder_spec.rb
+- spec/paged_groups/paged_groups_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/bluemarblepayroll/paged_groups
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.8
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: Create an evenly paged dataset of un-evenly sized groups
+test_files:
+- spec/paged_groups/builder_spec.rb
+- spec/paged_groups/paged_groups_spec.rb
+- spec/spec_helper.rb