superfeature 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3b624d4e0260cabbdebb2675fc22a8236889d92197859336a19700528e23b07
+  data.tar.gz: '09256cd31eea44abffe554ad183fb98ce061dcc416259d5b47b55651019edac2'
+SHA512:
+  metadata.gz: 02070efdf5658cce58e722464d2932f4908dfa0a848ac50adcc0adda1809566a25cbed61e206a759fd782782e4399639ece9f392d4d631d551c3c36dbb91bbb5
+  data.tar.gz: 0304f49be57b23352e1e8857b6a2e75b92c1dc71fe23c44151e85409b9bb2bd9a8b5f04f4bf8cf9ac5f7d0066d0129945412e739c5c7903b23d78fae05828f5b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Brad Gessler
+
+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,129 @@
+# Superfeature
+
+Features are simple boolean flags that say whether or not they're enabled, right? Not quite. Features can get quite complicated, as you'll read below in the use cases.
+
+This gem makes reasoning through those complexities much more sane by isolating them all into the `app/features` folder as plain 'ol Ruby objects (POROS), that way your team can reason through the features available in an app much better, test them, and do really complicated stuff when needed.
+
+## Use cases
+
+Here's why you should use Superfeature:
+
+### Turbo app built by a solopreneur deployed to the Apple App Store
+
+If you're deploying a simple Rails Turbo application to the web you might have 20 features that are available for purchase, but when deployed to the Apple App Store, you have to disable certain parts of your website to comply with their draconian app store policies. Superfeature could disable the features that upset Apple, like links to your support and pricing, so that your app can get approved and stay in compliance.
+
+### B2B Rails app built by a 50 person engineering team for multinational enterprises
+
+Enterprise use-cases are even more complicated. If a package is sold to a multi-national customer with 200 features, they may want to disable 30 of those features for certain teams/groups within that organization for compliance reasons. You end up with a hierarchy that can get as complicated as, "The Zig Bang feature is available to MegaCorp on the Platimum plan, but only for their US entities if their team administrators turn that feature on because of weird compliance reasons".
+
+## Installation
+
+Install the gem by executing the following from your Rails root:
+
+```bash
+$ bundle add superfeature
+```
+
+Then run
+
+```bash
+$ rails generate superfeature:install
+```
+
+Restart your server and it's off to the races!
+
+First thing you'll want to checkout is the `./app/plans/application_plan.rb` file:
+
+```ruby
+class ApplicationPlan < Superfeature::Plan
+  attr_reader :user, :account
+
+  def initialize(user)
+    @user = user
+    @account = user.account
+  end
+
+  def team_size
+    hard_limit maximum: 0, quantity: account.users.count
+  end
+
+  def moderation
+    enabled account.moderation_enabled?
+  end
+
+  def support
+    disabled
+  end
+end
+```
+
+Here's what it would look like when you add an enterprise plan to the lign up in the ``./app/plans/application_plan.rb`` file.
+
+```ruby
+class EnerprisePlan < ApplicationPlan
+  def support = enabled
+  def saml = enabled
+end
+```
+
+## Usage
+
+Then you can do things from controllers like:
+
+```ruby
+class ModerationController < ApplicationController
+  def show
+    if feature.moderation.enabled?
+      render "moderation"
+    else
+      redirect_to moderation_upgrade_path
+    end
+  end
+
+  protected
+
+  def plan = ApplicationPlan.new
+  def feature = plan.moderation
+end
+```
+
+Or from views:
+
+```erb
+<h1>Moderation</h1>
+<% if feature.enabled? %>
+  <p><% render partial: "moderation" %></p>
+<% else %>
+  <p>Call sales to upgrade to moderation</p>
+<% end %>
+```
+
+## Comparable libraries
+
+There's a few pretty great feature flag libraries that are worth mentioning so you can better evaluate what's right for you.
+
+### Flipper
+
+https://github.com/jnunemaker/flipper
+
+Flipper is probably the most extensive and mature feature flag libraries. It even comes with its own cloud service. As a library, it concerns itself with:
+
+* Persisting feature flags to Redis, ActiveRecord, or any custom back-end.
+* UI for toggling features flags on/off
+* Controlling feature flags for everybody, specific people, groups of people, or a percentage of people.
+
+Superfeature is different in that it:
+
+* Feature flags are testable.
+* Features are versioned and tracked as code, which makes it easier to sync between environments if that's a requirement.
+* Can handle reasoning about features beyond a simple true/false, including soft limits, app store limitations, or complex feature cascading required by some enterprises.
+
+### Rollout
+
+https://github.com/FetLife/rollout
+
+Roll-out is similar to Flipper, but is backed soley by Redis.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/superfeature_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/superfeature .css

data/app/assets/stylesheets/superfeature/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/concerns/superfeature/authorization.rb

@@ -0,0 +1,12 @@
+module Superfeature::Authorization
+  extend ActiveSupport::Concern
+
+  included do
+    helper_method :current_plan
+  end
+
+  protected
+    def current_plan
+      ApplicationPlan.new
+    end
+end

data/app/controllers/superfeature/application_controller.rb

@@ -0,0 +1,4 @@
+module Superfeature
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/superfeature/application_helper.rb

@@ -0,0 +1,4 @@
+module Superfeature
+  module ApplicationHelper
+  end
+end

data/app/jobs/superfeature/application_job.rb

@@ -0,0 +1,4 @@
+module Superfeature
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/superfeature/application_mailer.rb

@@ -0,0 +1,6 @@
+module Superfeature
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/superfeature/application_record.rb

@@ -0,0 +1,5 @@
+module Superfeature
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/views/layouts/superfeature/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Superfeature</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "superfeature/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+Superfeature::Engine.routes.draw do
+end

data/lib/superfeature/engine.rb

@@ -0,0 +1,5 @@
+module Superfeature
+  class Engine < ::Rails::Engine
+    isolate_namespace Superfeature
+  end
+end

data/lib/superfeature/version.rb

@@ -0,0 +1,3 @@
+module Superfeature
+  VERSION = "0.1.2"
+end

data/lib/superfeature.rb

@@ -0,0 +1,123 @@
+require "superfeature/version"
+require "superfeature/engine"
+
+module Superfeature
+  def self.plan(&)
+    Class.new(Superfeature::Plan, &)
+  end
+
+  class Feature
+    attr_reader :plan, :limit, :name
+    delegate :enabled?, :disabled?, to: :limit
+    delegate :upgrade, :downgrade, to: :plan
+
+    def initialize(plan:, name:, limit: Limit::Base.new)
+      @plan = plan
+      @limit = limit
+      @name = name
+    end
+  end
+
+  module Limit
+    class Base
+      def enabled?
+        false
+      end
+
+      def disabled?
+        not enabled?
+      end
+    end
+
+    class Hard < Base
+      attr_accessor :quantity, :maximum
+
+      def initialize(quantity: , maximum: )
+        @quantity = quantity
+        @maximum = maximum
+      end
+
+      def remaining
+        maximum - quantity
+      end
+
+      def exceeded?
+        quantity > maximum if quantity and maximum
+      end
+
+      def enabled?
+        not exceeded?
+      end
+    end
+
+    class Soft < Hard
+      attr_accessor :quantity, :soft_limit, :hard_limit
+
+      def initialize(quantity:, soft_limit:, hard_limit:)
+        @quantity = quantity
+        @soft_limit = soft_limit
+        @hard_limit = hard_limit
+      end
+
+      def maximum
+        @soft_limit
+      end
+    end
+
+    # Unlimited is treated like a Soft, initialized with infinity values.
+    # It is recommended to set a `soft_limit` value based on the technical limitations
+    # of your application unless you're running a theoritcal Turing Machine.
+    #
+    # See https://en.wikipedia.org/wiki/Turing_machine for details.
+    class Unlimited < Soft
+      INFINITY = Float::INFINITY
+
+      def initialize(quantity: nil, hard_limit: INFINITY, soft_limit: INFINITY, **)
+        super(quantity:, hard_limit:, soft_limit:, **)
+      end
+    end
+
+    class Boolean < Base
+      def initialize(enabled:)
+        @enabled = enabled
+      end
+
+      def enabled?
+        @enabled
+      end
+    end
+  end
+
+  class Plan
+    def upgrade
+    end
+
+    def downgrade
+    end
+
+    protected
+      def hard_limit(**)
+        Limit::Hard.new(**)
+      end
+
+      def soft_limit(**)
+        Limit::Soft.new(**)
+      end
+
+      def unlimited(**)
+        Limit::Unlimited.new(**)
+      end
+
+      def enabled(value = true, **)
+        Limit::Boolean.new enabled: value, **
+      end
+
+      def disabled(value = true)
+        enabled !value
+      end
+
+      def feature(name, **)
+        Feature.new(plan: self, name:, **)
+      end
+  end
+end

data/lib/tasks/superfeature_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :superfeature do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: superfeature
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Brad Gessler
+bindir: bin
+cert_chain: []
+date: 2025-10-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Features can get really complicated when you have to cascade them from
+  global, account, policy, group, and policy levels. Superfeature makes that easy!
+email:
+- bradgessler@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/superfeature_manifest.js
+- app/assets/stylesheets/superfeature/application.css
+- app/controllers/concerns/superfeature/authorization.rb
+- app/controllers/superfeature/application_controller.rb
+- app/helpers/superfeature/application_helper.rb
+- app/jobs/superfeature/application_job.rb
+- app/mailers/superfeature/application_mailer.rb
+- app/models/superfeature/application_record.rb
+- app/views/layouts/superfeature/application.html.erb
+- config/routes.rb
+- lib/superfeature.rb
+- lib/superfeature/engine.rb
+- lib/superfeature/version.rb
+- lib/tasks/superfeature_tasks.rake
+homepage: https://github.com/rubymonolith/superfeature
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rubymonolith/superfeature
+  source_code_uri: https://github.com/rubymonolith/superfeature
+  changelog_uri: https://github.com/rubymonolith/superfeature
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Powerful cascading feature flags in Rails.
+test_files: []