blueprinter 0.25.3 → 0.30.0

data/README.md

@@ -1,23 +1,38 @@
-[![CircleCI](https://circleci.com/gh/procore/blueprinter.svg?style=svg)](https://circleci.com/gh/procore/blueprinter)
+[![Test](https://github.com/procore-oss/blueprinter/actions/workflows/test.yaml/badge.svg?branch=master)](https://github.com/procore-oss/blueprinter/actions/workflows/test.yaml)
 [![Gem Version](https://badge.fury.io/rb/blueprinter.svg)](https://badge.fury.io/rb/blueprinter)
 [![Gitter chat](https://badges.gitter.im/procore/blueprinter.svg)](https://gitter.im/blueprinter-gem/community)
 
 <img src="blueprinter_logo.svg" width="25%">
 
+# Recent Organization Move
+
+Please change your local remote to pull from this repository:
+
+```bash
+git remote set-url [previous-remote-name] git@github.com:procore-oss/blueprinter.git
+```
+
+to see the previous upstream remote name, run:
+
+```bash
+git remote -v
+```
+
 # Blueprinter
+
 Blueprinter is a JSON Object Presenter for Ruby that takes business objects and breaks them down into simple hashes and serializes them to JSON. It can be used in Rails in place of other serializers (like JBuilder or ActiveModelSerializers). It is designed to be simple, direct, and performant.
 
 It heavily relies on the idea of `views` which, similar to Rails views, are ways of predefining output for data in different contexts.
 
 ## Documentation
+
 Docs can be found [here](http://www.rubydoc.info/gems/blueprinter).
 
 ## Usage
+
 <details open>
 <summary>Basic</summary>
 
----
-
 If you have an object you would like serialized, simply create a blueprint. Say, for example, you have a User record with the following attributes `[:uuid, :email, :first_name, :last_name, :password, :address]`.
 
 You may define a simple blueprint like so:
@@ -31,6 +46,7 @@ end
 ```
 
 and then, in your code:
+
 ```ruby
 puts UserBlueprint.render(user) # Output is a JSON string
 ```
@@ -45,15 +61,11 @@ And the output would look like:
   "last_name": "Doe"
 }
 ```
-
----
 </details>
 
-
 <details>
 <summary>Collections</summary>
 
----
 
 You can also pass a collection object or an array to the render method.
 
@@ -80,14 +92,28 @@ This will result in JSON that looks something like this:
 ]
 ```
 
----
-</details>
 
+You can also configure other classes to be treated like collections. For example, if you are using Mongoid, you can configure it to treat `Mongoid::Criteria` objects as collections:
+
+```ruby
+Blueprinter.configure do |config|
+  config.custom_array_like_classes = [Mongoid::Criteria]
+end
+```
+
+Or if you wanted it to treat the `Set` class as a collection:
+
+```ruby
+Blueprinter.configure do |config|
+  config.custom_array_like_classes = [Set]
+end
+```
+
+</details>
 
 <details>
 <summary>Renaming</summary>
 
----
 
 You can rename the resulting JSON keys in both fields and associations by using the `name` option.
 
@@ -111,16 +137,14 @@ This will result in JSON that looks something like this:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>Views</summary>
 
----
 
 You may define different outputs by utilizing views:
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
@@ -137,14 +161,17 @@ class UserBlueprint < Blueprinter::Base
   end
 end
 ```
+
 A view can include fields from another view by utilizing `include_view` and `include_views`.
 
 Usage:
+
 ```ruby
 puts UserBlueprint.render(user, view: :extended)
 ```
 
 Output:
+
 ```json
 {
   "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
@@ -155,16 +182,38 @@ Output:
 }
 ```
 
----
 </details>
 
+<details>
+<summary>Identifiers</summary>
+
+
+`identifier`s are used to specify a field or method name used as an identifier. Usually, this is something like `:id`.
+
+Example:
+
+```rb
+class UserBlueprint < Blueprinter::Base
+  identifier :uuid
+end
+```
+
+Blueprinter `identifier`s have a few properties that set them apart from `field`s.
+
+1. Identifiers are **always** rendered and considered their own view (the `:identifier` view).
+2. When rendering, identifier fields are always sorted first, before other fields.
+
+If either of the above two developer conveniences are not desired, you can simply create your identifier fields as regular `field`s.
+
+
+</details>
 
 <details>
 <summary>Root</summary>
-
----
+<a name="root"></a>
 
 You can also optionally pass in a root key to wrap your resulting json in:
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
@@ -177,11 +226,13 @@ end
 ```
 
 Usage:
+
 ```ruby
 puts UserBlueprint.render(user, view: :normal, root: :user)
 ```
 
 Output:
+
 ```json
 {
   "user": {
@@ -193,16 +244,14 @@ Output:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>Meta Attributes</summary>
 
----
 
 You can additionally add meta-data to the json as well:
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
@@ -215,6 +264,7 @@ end
 ```
 
 Usage:
+
 ```ruby
 json = UserBlueprint.render(user, view: :normal, root: :user, meta: {links: [
   'https://app.mydomain.com',
@@ -224,6 +274,7 @@ puts json
 ```
 
 Output:
+
 ```json
 {
   "user": {
@@ -240,18 +291,17 @@ Output:
   }
 }
 ```
+
 _NOTE:_ For meta attributes, a [root](#root) is mandatory.
 
----
 </details>
 
-
 <details>
 <summary>Exclude Fields</summary>
 
----
 
 You can specifically choose to exclude certain fields for specific views
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
@@ -270,11 +320,13 @@ end
 ```
 
 Usage:
+
 ```ruby
 puts UserBlueprint.render(user, view: :extended)
 ```
 
 Output:
+
 ```json
 {
   "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
@@ -303,16 +355,14 @@ class UserBlueprint < Blueprinter::Base
 end
 ```
 
----
 </details>
 
-
 <details>
 <summary>Associations</summary>
 
----
 
 You may include associated objects. Say for example, a user has projects:
+
 ```ruby
 class ProjectBlueprint < Blueprinter::Base
   identifier :uuid
@@ -331,11 +381,13 @@ end
 ```
 
 Usage:
+
 ```ruby
 puts UserBlueprint.render(user, view: :normal)
 ```
 
 Output:
+
 ```json
 {
   "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
@@ -357,6 +409,7 @@ Output:
 
 It is also possible to pass options from one Blueprint to another via an association.
 For example:
+
 ```ruby
 class VehicleBlueprint < Blueprinter::Base
   identifier :uuid
@@ -375,18 +428,16 @@ class DriverBlueprint < Blueprinter::Base
 end
 ```
 
----
 </details>
 
-
 <details>
 <summary>Default Association/Field Option</summary>
 
----
 
 By default, an association or field that evaluates to `nil` is serialized as `nil`. A default serialized value can be specified as an option on the association or field for cases when the association/field could potentially evaluate to `nil`. You can also specify a global `field_default` or `association_default` in the Blueprinter config which will be used for all fields/associations that evaluate to nil.
 
-#### Global Config Setting
+### Global Config Setting
+
 ```ruby
 Blueprinter.configure do |config|
   config.field_default = "N/A"
@@ -394,7 +445,8 @@ Blueprinter.configure do |config|
 end
 ```
 
-#### Field-level/Association-level Setting
+### Field-level/Association-level Setting
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
@@ -406,51 +458,50 @@ class UserBlueprint < Blueprinter::Base
 end
 ```
 
----
 </details>
 
-
 <details>
 <summary>default_if</summary>
 
----
 
 Sometimes, you may want certain "empty" values to pass through to the default value.
 Blueprinter provides the ability to treat the following empty types as the default value (or `nil` if no default provided).
 
-#### Blueprinter::EMPTY_COLLECTION
+### Blueprinter::EMPTY_COLLECTION
+
 An empty array or empty active record collection.
 
-#### Blueprinter::EMPTY_HASH
+### Blueprinter::EMPTY_HASH
+
 An empty hash.
 
-#### Blueprinter::EMPTY_STRING
+### Blueprinter::EMPTY_STRING
+
 An empty string or symbol.
 
-#### Field-level/Association-level Setting
+#### Field-level/Association-level Setting - EMPTY_STRING
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
 
   view :normal do
     # If first_name is an empty string, it will become "N/A"
-    field :first_name, default_if: Blueprinter::EmptyString, default: "N/A"
+    field :first_name, default_if: Blueprinter::EMPTY_STRING, default: "N/A"
     # If the projects association collection is empty, it will become nil
-    association :projects, blueprint: ProjectBlueprint, default_if: Blueprinter::EmptyCollection
+    association :projects, blueprint: ProjectBlueprint, default_if: Blueprinter::EMPTY_COLLECTION
   end
 end
 ```
 
----
 </details>
 
-
 <details>
 <summary>Supporting Dynamic Blueprints For Associations</summary>
 
----
 
 When defining an association, we can dynamically evaluate the blueprint. This comes in handy when adding polymorphic associations, by allowing reuse of existing blueprints.
+
 ```ruby
 class Task < ActiveRecord::Base
   belongs_to :taskable, polymorphic: true
@@ -473,16 +524,14 @@ class TaskBlueprint < Blueprinter::Base
   end
 end
 ```
+
 _NOTE:_ `taskable.blueprint` should return a valid Blueprint class. Currently, `has_many` is not supported because of the very nature of polymorphic associations.
 
----
 </details>
 
-
 <details>
 <summary>Defining A Field Directly In The Blueprint</summary>
 
----
 
 You can define a field directly in the Blueprint by passing it a block. This is especially useful if the object does not already have such an attribute or method defined, and you want to define it specifically for use with the Blueprint. This is done by passing `field` a block. The block also yields the object and any options that were passed from `render`. For example:
 
@@ -510,14 +559,11 @@ Output:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>Defining An Identifier Directly In The Blueprint</summary>
 
----
 
 You can also pass a block to an identifier:
 
@@ -543,14 +589,11 @@ Output:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>Defining An Association Directly In The Blueprint</summary>
 
----
 
 You can also pass a block to an association:
 
@@ -588,14 +631,11 @@ Output:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>Passing Additional Properties To #render</summary>
 
----
 
 `render` takes an options hash which you can pass additional properties, allowing you to utilize those additional properties in the `field` block. For example:
 
@@ -623,18 +663,16 @@ Output:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>Conditional Fields</summary>
 
----
 
 Both the `field` and the global Blueprinter Configuration supports `:if` and `:unless` options that can be used to serialize fields conditionally.
 
-#### Global Config Setting
+### Global Config Setting - if and unless
+
 ```ruby
 Blueprinter.configure do |config|
   config.if = ->(field_name, obj, _options) { !obj[field_name].nil? }
@@ -643,6 +681,7 @@ end
 ```
 
 #### Field-level Setting
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
@@ -653,32 +692,32 @@ end
 
 _NOTE:_ The field-level setting overrides the global config setting (for the field) if both are set.
 
----
 </details>
 
-
 <details>
 <summary>Custom Formatting for Dates and Times</summary>
 
----
 
 To define a custom format for a Date or DateTime field, include the option `datetime_format`.
 This global or field-level option can be either a string representing the associated `strftime` format,
 or a Proc which receives the original Date/DateTime object and returns the formatted value.
 When using a Proc, it is the Proc's responsibility to handle any errors in formatting.
 
+#### Global Config Setting - datetime
 
-#### Global Config Setting
 If a global datetime_format is set (either as a string format or a Proc), this option will be
 invoked and used to format all fields that respond to `strftime`.
+
 ```ruby
 Blueprinter.configure do |config|
   config.datetime_format = ->(datetime) { datetime.nil? ? datetime : datetime.strftime("%s").to_i }
 end
 ```
 
-#### Field-level Setting
+#### Field-level Setting - datetime_format
+
 Usage (String Option):
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :name
@@ -687,6 +726,7 @@ end
 ```
 
 Output:
+
 ```json
 {
   "name": "John Doe",
@@ -695,6 +735,7 @@ Output:
 ```
 
 Usage (Proc Option):
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :name
@@ -703,6 +744,7 @@ end
 ```
 
 Output:
+
 ```json
 {
   "name": "John Doe",
@@ -712,14 +754,11 @@ Output:
 
 _NOTE:_ The field-level setting overrides the global config setting (for the field) if both are set.
 
----
 </details>
 
-
 <details>
 <summary>Transform Classes</summary>
 
----
 
 Blueprinter provides the ability to specify `transform`s on views, which enable further
 processing and transforming of resulting view field hashes prior to serialization.
@@ -731,6 +770,7 @@ Whatever is returned from this `transform` method will end up being the resultin
 #### Example
 
 Create a Transform class extending from `Blueprinter::Transformer`
+
 ```ruby
 class DynamicFieldTransformer < Blueprinter::Transformer
   def transform(hash, object, options)
@@ -752,6 +792,7 @@ end
 ```
 
 Then specify the transform to use for the view.
+
 ```ruby
 class UserBlueprint < Blueprinter::Base
   fields :first_name, :last_name
@@ -762,6 +803,7 @@ end
 #### Global Transforms
 
 You can also specify global default transformers. Create one or more transformer classes extending from `Blueprinter::Transformer` and set the `default_transformers` configuration
+
 ```ruby
 class LowerCamelTransformer < Blueprinter::Transformer
   def transform(hash, _object, _options)
@@ -778,19 +820,18 @@ end
 
 **Note: Any transforms specified on a per-blueprint or per-view level will override the `default_transformers` in the configuration.**
 
----
 </details>
 
 <details>
 <summary>Configurable Extractors</summary>
 
----
 
 Blueprinter gets a given objects' values from the fields definitions using extractor classes. You can substitute your own extractor class globally or per-field.
 
 #### Examples
 
 For a specific kind of field, create an extractor class extending from `Blueprinter::Extractor`
+
 ```ruby
 class MyFieldExtractor < Blueprinter::Extractor
   def extract(_field_name, _object, _local_options, _options={})
@@ -807,6 +848,7 @@ end
 ```
 
 For a global default, create an extractor class extending from `Blueprinter::AutoExtractor` and set the `extractor_default` configuration
+
 ```ruby
 class MyAutoExtractor < Blueprinter::AutoExtractor
   def initialize
@@ -830,13 +872,11 @@ Blueprinter.configure do |config|
 end
 ```
 
----
 </details>
 
 <details>
 <summary>Sorting Fields</summary>
 
----
 
 By default the response sorts the keys by name. If you want the fields to be sorted in the order of definition, use the below configuration option.
 
@@ -857,6 +897,7 @@ end
 ```
 
 Output:
+
 ```json
 {
   "name": "John Doe",
@@ -865,14 +906,11 @@ Output:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>Deprecations</summary>
 
----
 
 When functionality in Blueprinter is invoked, that has been deprecated, the default behavior is to
 write a deprecation notice to stderror.
@@ -885,21 +923,19 @@ However, deprecations can be configured to report at three different levels:
 | `:raise`            | Deprecations will be raised as `Blueprinter::BlueprinterError`s |
 | `:silence`          | Deprecations will be silenced and will not be raised or logged  |
 
-### Example:
+### Example - deprecations
+
 ```ruby
 Blueprinter.configure do |config|
   config.deprecations = :raise
 end
 ```
 
----
 </details>
 
-
 <details>
 <summary>render_as_hash</summary>
 
----
 
 Same as `render`, returns a Ruby Hash.
 
@@ -918,14 +954,11 @@ Output:
 }
 ```
 
----
 </details>
 
-
 <details>
 <summary>render_as_json</summary>
 
----
 
 Same as `render`, returns a Ruby Hash JSONified. This will call JSONify all keys and values.
 
@@ -944,11 +977,10 @@ Output:
 }
 ```
 
----
 </details>
 
-
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -956,13 +988,15 @@ gem 'blueprinter'
 ```
 
 And then execute:
+
 ```bash
-$ bundle
+bundle
 ```
 
 Or install it yourself as:
+
 ```bash
-$ gem install blueprinter
+gem install blueprinter
 ```
 
 You should also have `require 'json'` already in your project if you are not using Rails or if you are not using Oj.
@@ -1002,12 +1036,15 @@ end
 _NOTE:_ You should be doing this only if you aren't using `yajl-ruby` through the JSON API by requiring `yajl/json_gem`. More details [here](https://github.com/brianmario/yajl-ruby#json-gem-compatibility-api). In this case, `JSON.generate` is patched to use `Yajl::Encoder.encode` internally.
 
 ## Contributing
-Feel free to browse the issues, converse, and make pull requests. If you need help, first please see if there is already an issue for your problem. Otherwise, go ahead and make a new issue.
+
+Please read our [Contributing](CONTRIBUTING.md) file
 
 ### Tests
+
 You can run tests with `bundle exec rake`.
 
 ### Maintain The Docs
+
 We use Yard for documentation. Here are the following documentation rules:
 
 - Document all public methods we expect to be utilized by the end developers.
@@ -1022,7 +1059,9 @@ documentation rules:
 - Methods that are not set to private due to ruby visibility rule limitations should be marked with `@api private`.
 
 ### Releasing a New Version
+
 To release a new version, change the version number in `version.rb`, and update the `CHANGELOG.md`. Finally, maintainers need to run `bundle exec rake release`, which will automatically create a git tag for the version, push git commits and tags to Github, and push the `.gem` file to rubygems.org.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).