ar_serializer 1.2.3 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82a536d1726d005b8fe7606ba04dd252bd169a88686d67b6eb6fdb5f4f2e791d
-  data.tar.gz: fe03fd5cc99e41f4b9002fe43351f619e65f8a692049bd0af959432fe301e1d8
+  metadata.gz: ef5e6277909a8e2573068c3c8c2e19275c8763c9395f610cb0e8aebbce566eee
+  data.tar.gz: ad0b8f4f8961dcf576c402071f79b312e93c0a4da958bab46b420adb70ea5416
 SHA512:
-  metadata.gz: 86729d4da8d17051e42dcab42dec965163ed478e738459eed8633942f29ff5262e7691b726d785db4fdcbc2781c286d93d4972b400fa8bbfaf62d4dc8e196b30
-  data.tar.gz: 13d2d9d8c85004a4c02cb0988797395a1d2819535c03d8cb753ee0a2882177ea8a8d090cc1902289afc96ca89440a6530a71f840308d8e33ce9983af16203062
+  metadata.gz: 285562de1dc23efb39552eb7b184fb2004dfdf0a63314d161f5397060ca79c22136140612cde7f3d46bc76f3b649e016671fd15561d9829e4c14f22a42cf7c72
+  data.tar.gz: 3081e60e717cefe07b8629934babeacecef06c5ee059702cf8371e3214dd5c6fb7a489dd09cc8f5b31d9f8571ef4b8722c607dcce02145e2a5197bcd8a42c7cf

data/README.md

@@ -1,15 +1,19 @@
 # ArSerializer
 
-- JSONの形をclientからリクエストできる
-- N+1 SQLを避ける
+A serializer for ActiveRecord (and plain Ruby objects) where the **client requests the shape of the JSON**, GraphQL-style.
 
-## Install
+- The client decides which fields and associations to fetch, with a query.
+- Associations are batch-loaded, so deeply nested queries avoid N+1 SQL.
+- Generates TypeScript type definitions and can serve a GraphQL endpoint.
+
+## Installation
 
 ```ruby
 gem 'ar_serializer'
 ```
 
-## Field定義
+## Defining fields
+
 ```ruby
 class User < ActiveRecord::Base
   has_many :posts
@@ -27,20 +31,26 @@ class Comment < ActiveRecord::Base
 end
 ```
 
-## Serialize
+## Serializing
+
+```ruby
+ArSerializer.serialize(model, query, context: nil, use: nil)
+```
+
 ```ruby
 ArSerializer.serialize Post.find(params[:id]), params[:query]
 ```
 
 ## Query
+
+A query selects fields. Use `:*` for all fields, an array, or a hash; nested
+associations take a nested query.
+
 ```ruby
 ArSerializer.serialize user, :*
-# => {
-#   id: 1,
-#   name: "user1",
-#   posts: [{}, {}]
-# }
+# => { id: 1, name: "user1", posts: [{}, {}] }
 
+# Array form and hash form are equivalent:
 ArSerializer.serialize user, [:id, :name, posts: [:id, :title, comments: :id]]
 ArSerializer.serialize user, { id: true, name: true, posts: { id: true, title: true, comments: :id } }
 # => {
@@ -51,25 +61,36 @@ ArSerializer.serialize user, { id: true, name: true, posts: { id: true, title: t
 #     { id: 3, title: "title2", comments: [] }
 #   ]
 # }
+```
+
+Rename a field in the output with `as:`:
+
+```ruby
 ArSerializer.serialize posts, [:title, :body, comment_count: { as: :num_replies }]
-# => [
-#   { title: "title1", body: "body1", num_replies: 3 },
-#   { title: "title2", body: "body2", num_replies: 2 },
-#   { title: "title3", body: "body3", num_replies: 0 },
-#   { title: "title4", body: "body4", num_replies: 4 }
-# ]
+# => [{ title: "title1", body: "body1", num_replies: 3 }, ...]
 ```
 
-## その他
+## Field options
+
+### Computed fields (`data block`, `includes`)
+
+Pass a block to compute the value. `includes:` eager-loads the associations the
+block needs.
+
 ```ruby
-# data block, include
 class Comment < ActiveRecord::Base
-  serializer_field :username, includes: :user do
-    { ja: user.name + '先生', en: 'Dr.' + user.name }
+  serializer_field :title, includes: :user do
+    "#{user.name}'s comment"
   end
 end
+```
+
+### Preloading (avoid N+1)
 
-# preloader
+`preload:` receives **all** records being serialized and returns a lookup; the
+data block then reads from it per record.
+
+```ruby
 class Foo < ActiveRecord::Base
   bar_count_loader = ->(models) do
     Bar.where(foo_id: models.map(&:id)).group(:foo_id).count
@@ -77,59 +98,136 @@ class Foo < ActiveRecord::Base
   serializer_field :bar_count, preload: bar_count_loader do |preloaded|
     preloaded[id] || 0
   end
-  # data_blockが `do |preloaded| preloaded[id] end` の場合は省略可能
+  # When the data block is exactly `do |preloaded| preloaded[id] end`, it can be omitted.
 end
+```
 
-# order and limits
-class Post < ActiveRecord::Base
-  has_many :comments
-  serializer_field :comments
-end
+### Counts
+
+```ruby
+serializer_field :comment_count, count_of: :comments
+```
+
+### Order and limits
+
+Associations accept `order_by`, `direction`, `first`/`last` params.
+
+```ruby
 ArSerializer.serialize Post.all, { comments: [:id, params: { order_by: :createdAt, direction: :desc, first: 10 }] }
 ArSerializer.serialize Post.all, { comments: [:id, params: { order_by: :updatedAt, last: 10 }] }
+```
+
+### Context and params
 
-# context and params
+The block receives the serialize-time `context` and any query `params`.
+
+```ruby
 class Post < ActiveRecord::Base
   serializer_field :created_at do |context, **params|
     created_at.in_time_zone(context[:tz]).strftime params[:format]
   end
 end
 ArSerializer.serialize post, { created_at: { params: { format: '%H:%M:%S' } } }, context: { tz: 'Tokyo' }
+```
 
-# camelcase
+### camelCase field names
+
+```ruby
 class Foo < ActiveRecord::Base
   def foo_bar; end
   serializer_field :fooBar
 end
+```
 
-# non activerecord class
-class Foo
-  include ArSerializer::Serializable
-  def bar; end
-  serializer_field :bar
+### Aliasing an association (`association:`)
+
+Expose an association under a different name.
+
+```ruby
+class User < ActiveRecord::Base
+  serializer_field :articles, association: :posts
 end
+ArSerializer.serialize user, { articles: :title }
+```
 
-# namespace
+### Restricting fields (`only` / `except`)
+
+Limit which fields of the associated records may be queried. Combine with
+`association:` when the field name differs from the association.
+
+```ruby
+class User < ActiveRecord::Base
+  serializer_field :posts, only: :title                       # restrict
+  serializer_field :entries, association: :posts, except: :body  # alias + restrict
+end
+ArSerializer.serialize user, { posts: :title }    #=> ok
+ArSerializer.serialize user, { posts: :body }     #=> Error (not allowed by `only`)
+ArSerializer.serialize user, { entries: :title }  #=> ok
+ArSerializer.serialize user, { entries: :body }   #=> Error (excluded by `except`)
+```
+
+## Access control
+
+### Field-level: `permission:`
+
+Guards a single field. When the predicate returns false the field is omitted
+from the output.
+
+```ruby
+serializer_field :email, permission: ->(current_user) { current_user&.admin? }
+```
+
+### Model-level: `serializer_permission`
+
+Guards every instance of a class, **no matter which query path reaches it**.
+When serializing, each candidate object is checked and objects failing the
+predicate are dropped — a single reference becomes `null`, an array drops the
+element. Useful because any field reachable through the query graph is otherwise
+fetchable.
+
+```ruby
+class Document < ActiveRecord::Base
+  belongs_to :user
+  serializer_permission do |current_user|
+    current_user && current_user.id == user_id
+  end
+  serializer_field :id, :title
+end
+```
+
+## Namespaces
+
+Fields can be grouped into namespaces and exposed only when requested via `use:`.
+
+```ruby
 class User < ActiveRecord::Base
   serializer_field :name
   serializer_field(:foo, namespace: :admin) { :foo }
   serializer_field(:bar, namespace: :superadmin) { :bar }
 end
-ArSerializer.serialize user, [:name, :foo] #=> Error
+ArSerializer.serialize user, [:name, :foo]                          #=> Error
 ArSerializer.serialize user, [:name, :foo], use: :admin
 ArSerializer.serialize user, [:name, :foo, :bar], use: [:admin, :superadmin]
+```
 
-# only, except
-class User < ActiveRecord::Base
-  serializer_field :o_posts, association: :posts, only: :title
-  serializer_field :e_posts, association: :posts, except: :comments
+## Non-ActiveRecord classes
+
+Include `ArSerializer::Serializable` to use the DSL on plain Ruby objects.
+
+```ruby
+class Foo
+  include ArSerializer::Serializable
+  def bar; end
+  serializer_field :bar
 end
-ArSerializer.serialize user, { o_posts: :title, e_posts: :body }
-ArSerializer.serialize user, { o_posts: :*, e_posts: :* }
-ArSerializer.serialize user, { o_posts: :body } #=> Error
-ArSerializer.serialize user, { e_posts: :comments } #=> Error
+```
 
-# types
+## TypeScript types
+
+Declare types with `type:` / `params_type:`, then generate `.d.ts`-style
+definitions.
+
+```ruby
 class User < ActiveRecord::Base
   serializer_field(:posts, params_type: { title: :string? }) do |title: nil|
     title ? posts.where(title: title) : posts
@@ -139,10 +237,16 @@ class User < ActiveRecord::Base
   end
   serializer_field :published_posts, type: -> { [Post] }
 end
+
 ArSerializer::TypeScript.generate_type_definition User
-# => export type TypeUser {...}; export type TypePost {...}; ...
+# => export type TypeUser = {...}; export type TypePost = {...}; ...
+```
+
+## GraphQL
 
-# graphql
+Expose a schema object and serve GraphQL queries against it.
+
+```ruby
 class MySchema
   include ArSerializer::Serializable
   serializer_field :post, type: Post do |context, id:|
@@ -155,7 +259,12 @@ class MySchema
     ArSerializer::GraphQL::SchemaClass.new self.class
   end
 end
+
 ArSerializer::GraphQL.definition MySchema # schema.graphql
-ArSerializer::GraphQL.serialize MySchema.new, '{post(id: 1){title} user(name: user1){id name}}'
-ArSerializer::GraphQL.serialize MySchema.new, '{__schema{types{name fields{ name}}}}', operation_name: nil, variables: {}
+ArSerializer::GraphQL.serialize MySchema.new, '{ post(id: 1){ title } user(name: "user1"){ id name } }'
+ArSerializer::GraphQL.serialize MySchema.new, '{ __schema { types { name fields { name } } } }', operation_name: nil, variables: {}
 ```
+
+## License
+
+[MIT](LICENSE.txt)

data/gemfiles/Gemfile-rails-7

@@ -7,4 +7,3 @@ gemspec path: ".."
 
 gem "sqlite3", "~> 1.4"
 gem "activerecord", "~> 7.0"
-gem "benchmark"

data/gemfiles/Gemfile-rails-8

@@ -7,4 +7,3 @@ gemspec path: ".."
 
 gem "sqlite3"
 gem "activerecord", "~> 8.0"
-gem "benchmark"

data/lib/ar_serializer/serializer.rb

@@ -85,6 +85,7 @@ module ArSerializer::Serializer
         raise ArgumentError, "No permission field #{permission} for #{klass}" unless permission_field
       end
       if permission_field
+        ArSerializer.preload_associations models, permission_field.includes if permission_field.includes.present?
         preloadeds = permission_field.preloaders.map do |p|
           preloader_values[[p, nil]] ||= preload.call p, nil
         end
@@ -95,6 +96,7 @@ module ArSerializer::Serializer
 
       defaults = klass._serializer_field_info :defaults
       if defaults
+        ArSerializer.preload_associations models, defaults.includes if defaults.includes.present?
         defaults.preloaders.each do |p|
           preloader_values[[p, nil]] ||= preload.call p, nil
         end
@@ -181,7 +183,7 @@ module ArSerializer::Serializer
       end
 
       if defaults
-        preloadeds = defaults.preloaders.map { |p| preloader_values[[p]] } || []
+        preloadeds = defaults.preloaders.map { |p| preloader_values[[p, nil]] } || []
         models.each do |model|
           data = model.instance_exec(*preloadeds, context, {}, &defaults.data_block)
           output_for_model[model].update data

data/lib/ar_serializer/version.rb

@@ -1,3 +1,3 @@
 module ArSerializer
-  VERSION = '1.2.3'
+  VERSION = '1.2.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ar_serializer
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.2.4
 platform: ruby
 authors:
 - tompng