simple_ams 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5193c4f1997cfc84c8fdf5fa90abfde7ac2a03a2
+  data.tar.gz: 13c6c665417899d0a73d9900144d58e8f848e370
+SHA512:
+  metadata.gz: b6affb011516c6e9b69b829c176966305b38f7d102b874248bac63fb089c8b84b27cec6190e067364943935b26164bcc066d12ebad77c88d412edaf7db6724aa
+  data.tar.gz: c44a84ff86b1a0d2eb5b67670b508a3cfa6da2ded1cc0353fd0709b73a352a7a2d1bf735860cba76ae03f696e4eefab50c4704b67229be8fb1285f43376c8ea2

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/coverage/
+.envrc
+# rspec failure tracking
+.rspec_status
+.todo.md

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.1
+before_install: gem install bundler -v 1.15.4

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in SimpleAMS.gemspec
+gemspec

data/README.md

@@ -0,0 +1,224 @@
+# SimpleAMS
+> "Simple things should be simple and complex things should be possible." Alan Kay.
+
+If we want to interact with modern APIs we should start building modern, flexible libraries
+that help developers to build such APIs. Modern Ruby serializers, as I always wanted them to be.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'simple_ams'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install simple_ams
+
+## Usage
+The gem's interface has been inspired by ActiveModel Serializers 0.9.2, 0.10.stable, jsonapi-rb and Ember Data.
+However, **it has been built for POROs, does not rely in any dependency and does not relate to Rails in any case** other than
+some nostalgia for the (advanced at that time) pre-0.10 ActiveModel Serialiers.
+
+
+### Simple case
+
+You will rarely need all the advanced options. Usually you will have something like that:
+
+```ruby
+class UserSerializer
+  include SimpleAMS::DSL
+
+  #specify the adapter, pass some options all the way down to the adapter
+  adapter SimpleAMS::Adapters::JSONAPI, root: true
+
+  #specify available attributes/fields
+  attributes :id, :name, :email, :birth_date
+
+  #specify available relations
+  has_many :videos, :comments, :posts
+  belongs_to :organization
+  has_one :profile
+
+  #specify some links
+  link :feed, '/api/v1/me/feed'
+  #links can also take other options, as specified by RFC 8288
+  link :root, '/api/v1/', rel: :user
+  #link values can be dynamic as well through lambdas
+  link :posts, ->(obj) { "/api/v1/users/#{obj.id}/posts/" }, rel: :user
+  #if you also need dynamic options, you can return an array from the lambda
+  link :followers, ->(obj) { ["/api/v1/users/#{obj.id}/followers/", rel: obj.type] }
+
+  #same with metas: can be static, dynamic and accept arbitrary options
+  meta :environment, ->(obj) { Rails.env.to_s }
+
+  #collection accepts exactly the same aforementioned interface
+  #although you will rarely use it to full extend
+  #here we use only links and meta
+  collection do
+    link :root, '/api/v1/', rel: :user
+    type :users
+    meta :count, ->(collection) { collection.count }
+  end
+
+  #note that there is a shortcut if you just need to specify the collection name/type:
+  #collection :users
+
+  #override an attribute
+  def name
+    "#{object.first_name} #{object.last_name}"
+  end
+
+  #override a relation
+  def videos
+    Videos.where(user_id: object.id).published
+  end
+end
+```
+
+Then you can just feed your serializer with data, along with some options:
+
+```ruby
+SimpleAMS::Renderer.new(user, fields: [:id, :name, :email], includes: [:videos]).to_json
+```
+`to_json` first calls `as_json`, which creates a ruby Hash and then `to_json` is called
+on top of that hash.
+
+
+# Advanced usage
+The DSL in the previous example is just syntactic sugar. In the basis, there is a very powerful
+hash-based DSL that can be used in 3 different places:
+
+* When initializing the `SimpleAMS::Renderer` class to render the data using specific serializer, adapter and options.
+* Inside a class that has the `SimpleAMS::DSL` included, using the `with_options({})` class method
+* Through the DSL, powered with some syntactic sugar
+
+In any case, we have the following options:
+
+```ruby
+{
+  #the primary id of the record(s), used mostly by the underlying adapter (like JSONAPI)
+  primary_id: :id,
+  #the type of the record, used mostly by the underlying adapter (like JSONAPI)
+  type: :user,
+  #which relations should be included
+  includes: [:posts, videos: [:comments]],
+  #which fields for each relation should be included
+  fields: [:id, :name, posts: [:id, :text], videos: [:id, :title, comments: [:id, :text]]] #overrides includes when association is specified
+  relations: [
+    [:belongs_to, :company, {
+      serializer: CompanySerializer,
+      fields: Company.column_names.map(&:to_sym)
+      }
+    ],
+    [:has_many, :followers, {
+      serializer: UserSerializer,
+      fields: User.column_names.map(&:to_sym)
+    ],
+  ]
+  #the serializer that should be used
+  #makes sense to use it when initializing the Renderer
+  serializer: UserSerializer,
+  #can also be a lambda, in case of polymorphic records, ideal for ArrayRenderer
+  serializer: ->(obj){ obj.employee? ? EmployeeSerializer : UserSerializer }
+  #specifying the underlying adapter. This cannot be a lambda in case of ArrayRenderer,
+  #but can take some useful options that are passed down straight to the adapter class.
+  adapter: SimpleAMS::Adapters::AMS, root: true
+  #the links data
+  links: {
+    #can be a simple string
+    root: '/api/v1'
+    #a string with some options (relation and target attributes as defined by RFC8288
+    #however, you can also pass adapter-specific attributes
+    posts: "/api/v1/posts/", rel: :posts,
+    #it can also be a lambda that takes the resource to be rendered as a param
+    #when the lambda is called, it should return the array structure above
+    self: ->(obj) { ["/api/v1/users/#{obj.id}", rel: :user] }
+  },
+  #the meta data, same as the links data (available in adapters even for single records)
+  metas: {
+    type: ->(obj){ obj.employee? ? :employee : :user}
+    #meta can take arbitrary options as well
+    authorization: :oauth, type: :bearer_token
+  },
+  #collection parameters, used only in ArrayRenderer
+  collection: {
+    links: {
+      root: '/api/v1'
+    },
+    metas: {
+      pages: ->(obj) { [obj.pages, collection: true]},
+      current_page: ->(obj) { [obj.current_page, collection: true] },
+      previous_page: ->(obj) { [obj.previous_page, collection: true] },
+      next_page: ->(obj) { [obj.next_page, collection: true] },
+      max_per_page: 50,
+    },
+  }
+  #exposing helpers that will be available inside the seriralizer
+  expose: {
+    #a class
+    current_user: User.first
+    #or a module
+    helpers: CommonHelpers
+  },
+}
+```
+
+Now let those options be `OPTIONS`. These can be fed to either the `SimpleAMS::Renderer`
+or to the serializer class itself using the `with_options` class method. Let's see how:
+
+```ruby
+class UserSerializer
+  include SimpleAMS::DSL
+
+  with_options({ #you can pass the same options as above ;)
+    primary_id: :id,
+    #   ...
+    #   ...
+    #   ...
+  })
+
+  def name
+    "#{object.first_name} #{object.last_name}"
+  end
+
+  def videos
+    Videos.where(user_id: object.id).published
+  end
+end
+```
+
+The same options can be passed when calling the `Renderer`. `Renderer` can override
+some properties, however in all properties that act as sets/arrays (like
+attributes/fields, includes, links etc.), **specified serializer options take precedence** over
+`Renderer` options.
+
+```ruby
+SimpleAMS::Renderer.new(user, {
+  primary_id: :id,
+  serializer: UserSerializer,
+  #   ...
+  #   ...
+  #   ...
+}).to_json
+
+```
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+But reports are very welcome at https://github.com/vasilakisfil/SimpleAMS. Please add as much info as you can (serializer and Renderer input)
+so that we can easily track down the bug.
+
+Pull requests are also very welcome on GitHub at https://github.com/vasilakisfil/SimpleAMS.
+However, to keep the code's sanity (AMS I am looking to you), **I will be very picky** on the code style and design,
+to match (my) existing code characteristics.
+Because at the end of the day, it's gonna be me who will maintain this thing.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "SimpleAMS"
+
+# 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(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/simple_ams/adapters/ams.rb

@@ -0,0 +1,85 @@
+require "simple_ams"
+
+class SimpleAMS::Adapters::AMS
+  attr_reader :document, :options
+
+  def initialize(document, options = {})
+    @document = document
+    @options = options
+  end
+
+  def as_json
+    hash = {}
+
+    #TODO: I think bang method for merging is way faster ?
+    hash = hash.merge(fields)
+    hash = hash.merge(relations)
+    hash = hash.merge(links: links) unless links.empty?
+    hash = hash.merge(metas: metas) unless metas.empty?
+
+    return hash
+  end
+
+  def fields
+    @fields ||= document.fields.inject({}){ |hash, field|
+      _value = field.value
+      hash[field.key] = _value.respond_to?(:as_json) ? _value.as_json : _value
+      hash
+    }
+  end
+
+  def links
+    @links ||= document.links.inject({}){ |hash, link|
+      _value = link.value
+      hash[link.name] = _value.respond_to?(:as_json) ? _value.as_json : _value
+      hash
+    }
+  end
+
+  def metas
+    @metas ||= document.metas.inject({}){ |hash, meta|
+      _value = meta.value
+      hash[meta.name] = _value.respond_to?(:as_json) ? _value.as_json : _value
+      hash
+    }
+  end
+
+  def relations
+    return {} if document.relations.empty?
+
+    @relations ||= document.relations.inject({}){ |hash, relation|
+      if relation.folder?
+        value = relation.documents.map{|doc| self.class.new(doc).as_json}
+      else
+        value = self.class.new(relation).as_json
+      end
+      hash[relation.name] = value
+
+      hash
+    }
+  end
+
+  class Collection < self
+    attr_reader :folder, :adapter, :options
+
+    def initialize(folder, options = {})
+      @folder = folder
+      @adapter = folder.adapter.value
+      @options = options
+    end
+
+    def as_json
+      if options[:root]
+        {folder.name => documents}
+      else
+        documents
+      end
+    end
+
+    def documents
+      return folder.documents.map{|document|
+        adapter.new(document).as_json
+      } || []
+    end
+  end
+end

data/lib/simple_ams/adapters.rb

@@ -0,0 +1,2 @@
+module SimpleAMS::Adapters
+end

data/lib/simple_ams/document/fields.rb

@@ -0,0 +1,66 @@
+require "simple_ams"
+
+module SimpleAMS
+  class Document::Fields
+    include Enumerable
+
+    attr_reader :members
+
+    def initialize(options)
+      @options = options
+      @members = options.fields #[:field1, :field2]
+    end
+
+    def [](key)
+      found = members.find{|field| field == key}
+      return nil unless found
+
+      return with_decorator(found)
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      members.each{ |key|
+        yield with_decorator(key)
+      }
+
+      self
+    end
+
+    private
+      attr_reader :options
+
+      def with_decorator(key)
+        Field.new(
+          options.resource,
+          options.serializer,
+          key,
+          options
+        )
+      end
+
+      class Field
+        attr_reader :key
+
+        #do we need to inject the whole options object?
+        def initialize(resource, serializer, key, options)
+          @resource = resource
+          @serializer = serializer
+          @key = key
+          @options = options
+        end
+
+        def value
+          return @value if defined?(@value)
+
+          return @value = serializer.send(key) if serializer.respond_to? key
+          binding.pry if resource.is_a?(Array)
+          return resource.send(key)
+        end
+
+        private
+          attr_reader :resource, :serializer
+      end
+  end
+end

data/lib/simple_ams/document/links.rb

@@ -0,0 +1,61 @@
+require "simple_ams"
+
+module SimpleAMS
+  class Document::Links
+    include Enumerable
+
+    attr_reader :members
+
+    def initialize(options)
+      @options = options
+      @members = options.links
+    end
+
+    def [](key)
+      found = members.find{|link| link.name == key}
+      return nil unless found
+
+      return with_decorator(found)
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      members.each{ |member|
+        yield with_decorator(member)
+      }
+
+      self
+    end
+
+    private
+      attr_reader :options
+
+      def with_decorator(link)
+        Link.new(link)
+      end
+
+      #memoization maybe ?
+      class Link
+        def initialize(link)
+          @link = link
+        end
+
+        def name
+          link.name
+        end
+
+        def value
+          link.respond_to?(:call) ? link.value.call : link.value
+        end
+
+        def options
+          link.options
+        end
+
+        private
+          attr_reader :link
+      end
+  end
+end
+

data/lib/simple_ams/document/metas.rb

@@ -0,0 +1,15 @@
+require "simple_ams"
+
+module SimpleAMS
+  class Document::Metas < Document::Links
+    def initialize(options)
+      super
+      @members = options.metas
+    end
+
+    class Meta < Document::Links::Link
+    end
+  end
+end
+
+

data/lib/simple_ams/document/relations.rb

@@ -0,0 +1,95 @@
+require "simple_ams"
+
+#TODO: Add memoization for the relations object (iteration + access)
+module SimpleAMS
+  class Document::Relations
+    include Enumerable
+
+    def initialize(options)
+      @options = options
+      @relations = options.relations
+      @serializer = options.serializer
+      @resource = options.resource
+    end
+
+    def [](key)
+      found = relations.find{|relation| relation.name == key}
+      return nil unless found
+
+      return relation_for(found)
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      relations.each{ |relation|
+        yield relation_for(relation)
+      }
+
+      self
+    end
+
+    def empty?
+      count == 0
+    end
+
+    private
+      attr_reader :options, :relations, :serializer, :resource
+
+      def relation_for(relation)
+        renderer_klass_for(relation).new(
+          SimpleAMS::Options.new(
+            relation_value_for(relation.name), relation_options_for(relation)
+          )
+        )
+      end
+
+      #TODO: rename that to relation and existing relation to relationship
+      def relation_value_for(name)
+        if serializer.respond_to?(name)
+          serializer.send(name)
+        else
+          resource.send(name)
+        end
+      end
+
+      #4 options are merged:
+      # *user injected when instantiating the SimpleAMS class
+      # *relation options injected from parent serializer
+      # *serializer class options
+      def relation_options_for(relation)
+        _relation_options = {
+          injected_options: (relation.options || {}).merge(
+            options.relation_options_for(
+              relation.name
+            ).merge(
+              expose: options.expose
+            )
+          ).merge(
+            _internal: {
+              module: serializer.class.to_s.rpartition('::').first
+            }
+          )
+        }
+        #TODO: deep merge, can we automate this somehow ?
+        _relation_options[:injected_options][:collection] = (_relation_options[:collection] || {}).merge(
+          name: relation.name
+        )
+
+        return _relation_options
+      end
+
+      def renderer_klass_for(relation)
+        renderer = SimpleAMS::Document
+        collection_renderer = renderer::Folder
+
+        relation.collection? ? collection_renderer : renderer
+      end
+
+=begin TODO: Add that as public method, should help performance in edge cases
+      def relationship_info_for(name)
+        relations.find{|i| i.name == name}
+      end
+=end
+  end
+end