typed_params 0.2.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33d8c91a43f6350140c1cb3f60e4e08376b87b1abf0d10de9d5a586451bb92c8
-  data.tar.gz: 81674fe29eb88a8c914dfb573983348cd9bfcd5251ecfb3b8a3f31ec81da4c7b
+  metadata.gz: 26b2e5feb7cf9a5dee31da13a451af45b0995fd586593d5ad0aff3619dbae7fb
+  data.tar.gz: b0c56e75dfa90e7252d088a848155631bd943707c2d64628d366275c040b319f
 SHA512:
-  metadata.gz: 732329c43641f5b8428ef8dda5f888b185715489e2ec1e15fab27bc9e7af8cfa204e0d7a2eb982d30f581d429ad0965b916efdec1766a0cc7ec0d509c08125b6
-  data.tar.gz: db115e20596f17fe47a6063ba83737256caa9f0f8b81e90ce728787fb230d08ac87e13e0708b6a92c8a671d097fe632a2ed4c29f6f518dc230c841485cd4c561
+  metadata.gz: 2ae0982eefae7e30a6f1d11bc3bf9494c9b94d752f3eb9b130d614a32c19c1b8795c3d2a25c34e50d66171d3a2aa84fbaa4137e6f78454d87da25dfbf30dd478
+  data.tar.gz: 6abda1500599b0d982b3808108efc1e9fff777316c5d158bcfe4aadad88612df9ccdc3e63cd2991ecb1c64f72145ae08fd60c9be262d774f14dac29a974a9c86

data/CHANGELOG.md

@@ -1,9 +1,13 @@
 # Changelog
 
+## 1.0.1
+
+- Fix namespaced schemas.
+
 ## 1.0.0
 
 - Initial release.
 
-## 0.1.0
+## 0.2.0
 
-- Test release.
+- Test release.

data/README.md

@@ -10,6 +10,32 @@ parameter schemas for Rails APIs.
 This gem was extracted from [Keygen](https://keygen.sh) and is being used in production
 to serve millions of API requests per day.
 
+```ruby
+class UsersController < ApplicationController
+  include TypedParams::Controller
+
+  rescue_from TypedParams::InvalidParameterError, -> err {
+    render_bad_request err.message, source: err.path.to_s
+  }
+
+  typed_params {
+    param :first_name, type: :string, optional: true
+    param :last_name, type: :string, optional: true
+    param :email, type: :string
+    param :password, type: :string
+  }
+  def create
+    user = User.new(user_params)
+
+    if user.save
+      render_created user, location: v1_user_url(user)
+    else
+      render_unprocessable_resource user
+    end
+  end
+end
+```
+
 Sponsored by:
 
 [![Keygen logo](https://github.com/keygen-sh/typed_params/assets/6979737/f2947915-2956-4415-a9c0-5411c388ea96)](https://keygen.sh)
@@ -27,13 +53,14 @@ Links:
   - [Defining schemas](#defining-schemas)
   - [Shared schemas](#shared-schemas)
   - [Configuration](#configuration)
-  - [Unpermitted parameters](#unpermitted-parameters)
   - [Invalid parameters](#invalid-parameters)
+  - [Unpermitted parameters](#unpermitted-parameters)
   - [Parameter options](#parameter-options)
   - [Shared options](#shared-options)
   - [Scalar types](#scalar-types)
   - [Non-scalar types](#non-scalar-types)
   - [Custom types](#custom-types)
+  - [Formats](#formats)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -87,6 +114,10 @@ To start, include the controller module:
 ```ruby
 class ApplicationController < ActionController::API
   include TypedParams::Controller
+
+  rescue_from TypedParams::InvalidParameterError, -> err {
+    render_bad_request err.message, source: err.path.to_s
+  }
 end
 ```
 
@@ -202,7 +233,7 @@ end
 
 By default, all root schemas are a [`:hash`](#hash-type) schema. This is because both
 `request.request_parameters` and `request.query_parameters` are hashes. Eventually,
-we'd like [to make that configurable](https://github.com/keygen-sh/typed_params/blob/67e9a34ce62c9cddbd2bd313e4e9f096f8744b83/lib/typed_params/controller.rb#L24-L27),
+we'd like [to make that configurable](https://github.com/keygen-sh/typed_params/blob/67e9a34ce62c9cddbd2bd313e4e9f096f8744b83/lib/typed_parameters/controller.rb#L24-L27),
 so that you could use a top-level array schema. You can create nested schemas via
 the [`:hash`](#hash-type) and [`:array`](#array-type) types.
 
@@ -235,6 +266,16 @@ class PostsController < ApplicationController
 end
 ```
 
+Named schemas can have an optional `:namespace` as well.
+
+```ruby
+typed_schema :post, namespace: :v1 do
+  param :title, type: :string, length: { within: 10..80 }
+  param :content, type: :string, length: { minimum: 100 }
+  param :author_id, type: :integer
+end
+```
+
 ### Configuration
 
 ```ruby
@@ -304,7 +345,7 @@ TypedParams.configure do |config|
   #
   # With an invalid `child_key`, the path would be:
   #
-  #   rescue_from TypedParams::UnpermittedParameterError, err -> {
+  #   rescue_from TypedParams::UnpermittedParameterError, -> err {
   #     puts err.path.to_s # => parentKey.childKey
   #   }
   #
@@ -312,50 +353,55 @@ TypedParams.configure do |config|
 end
 ```
 
-### Unpermitted parameters
-
-By default, `.typed_params` is [`:strict`](#strict-parameter). This means that if any unpermitted parameters
-are provided, a `TypedParams::UnpermittedParameterError` will be raised.
+### Invalid parameters
 
-For `.typed_query`, the default is non-strict. This means that any unpermitted parameters
-will be ignored.
+When a parameter is provided, but it fails validation (e.g. a type mismatch), a
+`TypedParams::InvalidParameterError` error will be raised.
 
-You can rescue this error at the application-level like so:
+You can rescue this error at the controller-level like so:
 
 ```ruby
 class ApplicationController < ActionController::API
-  rescue_from TypedParams::UnpermittedParameterError, err -> {
-    render_bad_request "unpermitted parameter: #{err.path.to_jsonapi_pointer}"
+  rescue_from TypedParams::InvalidParameterError, -> err {
+    render_bad_request "invalid parameter: #{err.message}", parameter: err.path.to_dot_notation
   }
 end
 ```
 
-The `TypedParams::UnpermittedParameterError` error object has the following attributes:
+The `TypedParams::InvalidParameterError` error object has the following attributes:
 
-- `#message` - the error message, e.g. `unpermitted parameter`.
-- `#path` - a `Path` object with a pointer to the unpermitted parameter.
-- `#source` - either `:params` or `:query`, depending on where the unpermitted parameter came from (i.e. request body vs URL, respectively).
+- `#message` - the error message, e.g. `type mismatch (received string expected integer)`.
+- `#path` - a `Path` object with a pointer to the invalid parameter.
+- `#source` - either `:params` or `:query`, depending on where the invalid parameter came
+  from (i.e. request body vs query parameters, respectively).
 
-### Invalid parameters
+### Unpermitted parameters
 
-When a parameter is provided, but it fails validation (e.g. a type mismatch), a
-`TypedParams::InvalidParameterError` error will be raised.
+By default, `.typed_params` is [`:strict`](#strict-parameter). This means that if any unpermitted parameters
+are provided, a `TypedParams::UnpermittedParameterError` will be raised.
 
-You can rescue this error at the application-level like so:
+For `.typed_query`, the default is non-strict. This means that any unpermitted parameters
+will be ignored.
+
+You can rescue this error at the controller-level like so:
 
 ```ruby
 class ApplicationController < ActionController::API
-  rescue_from TypedParams::InvalidParameterError, err -> {
-    render_bad_request "invalid parameter: #{err.message}", parameter: err.path.to_dot_notation
+  # NOTE: Should be rescued before TypedParams::InvalidParameterError
+  rescue_from TypedParams::UnpermittedParameterError, -> err {
+    render_bad_request "unpermitted parameter: #{err.path.to_jsonapi_pointer}"
   }
 end
 ```
 
-The `TypedParams::InvalidParameterError` error object has the following attributes:
+The `TypedParams::UnpermittedParameterError` error object has the following attributes:
 
-- `#message` - the error message, e.g. `type mismatch (received string expected integer)`.
-- `#path` - a `Path` object with a pointer to the invalid parameter.
-- `#source` - either `:params` or `:query`, depending on where the invalid parameter came from (i.e. request body vs URL, respectively).
+- `#message` - the error message, e.g. `unpermitted parameter`.
+- `#path` - a `Path` object with a pointer to the unpermitted parameter.
+- `#source` - either `:params` or `:query`, depending on where the unpermitted parameter came
+  from (i.e. request body vs query parameters, respectively).
+
+It inherits from [`TypedParams::InvalidParameterError`](#invalid-parameters).
 
 ### Parameter options
 
@@ -366,9 +412,9 @@ Parameters can have validations, transforms, and more.
 - [`:strict`](#strict-parameter)
 - [`:optional`](#optional-parameter)
 - [`:if` and `:unless`](#conditional-parameter)
-- [`:as`](#alias-parameter)
+- [`:as`](#rename-parameter)
 - [`:noop`](#noop-parameter)
-- [`:coerce`](#coerced-parameter)
+- [`:coerce`](#coerce-parameter)
 - [`:allow_blank`](#allow-blank)
 - [`:allow_nil`](#allow-nil)
 - [`:allow_non_scalars`](#allow-non-scalars)
@@ -438,14 +484,14 @@ param :role, type: :string, unless: :guest?
 
 The lambda will be evaled within the current controller context.
 
-#### Alias parameter
+#### Rename parameter
 
 Apply a transformation that renames the parameter.
 
 ```ruby
 param :user, type: :integer, as: :user_id
 
-typed_params # => { user_id: '...' }
+typed_params # => { user_id: 1 }
 ```
 
 In this example, the parameter would be accepted as `:user`, but renamed
@@ -461,7 +507,7 @@ param :foo, type: :string, noop: true
 
 By default, this is `false`.
 
-#### Coerced parameter
+#### Coerce parameter
 
 The parameter will be coerced if its type is coercible and the parameter has a
 type mismatch. The coercion can fail, e.g. `:integer` to `:hash`, and if it does,
@@ -522,7 +568,7 @@ By default, this is disabled.
 The parameter must be included in the array or range.
 
 ```ruby
-param :log_level, type: :string,  inclusion: { in: %w[DEBUG INFO WARN ERROR FATAL] }
+param :log_level, type: :string, inclusion: { in: %w[DEBUG INFO WARN ERROR FATAL] }
 param :priority, type: :integer, inclusion: { in: 0..9 }
 ```
 
@@ -531,7 +577,7 @@ param :priority, type: :integer, inclusion: { in: 0..9 }
 The parameter must be excluded from the array or range.
 
 ```ruby
-param :custom_log_level, type: :string,  exclusion: { in: %w[DEBUG INFO WARN ERROR FATAL] }
+param :custom_log_level, type: :string, exclusion: { in: %w[DEBUG INFO WARN ERROR FATAL] }
 param :custom_priority, type: :integer, exclusion: { in: 0..9 }
 ```
 
@@ -562,15 +608,15 @@ Transform the parameter using a lambda. This is commonly used to transform a
 parameter into a nested attributes hash or array.
 
 ```ruby
-param :user, type: :string, transform: -> _key, email {
-  [:user_attributes, { email: }]
+param :role, type: :string, transform: -> _, name {
+  [:role_attributes, { name: }]
 }
 ```
 
 The lambda must accept a key (the current parameter key), and a value (the
 current parameter value).
 
-The lamda must return a tuple with the new key and value.
+The lambda must return a tuple with the new key and value.
 
 #### Validate parameter
 
@@ -613,39 +659,39 @@ end
 
 #### String type
 
-Defines a string parameter. Must be a `String`.
+Type `:string`. Defines a string parameter. Must be a `String`.
 
 #### Boolean type
 
-Defines a boolean parameter. Must be `TrueClass` or `FalseClass`.
+Type `:boolean`. Defines a boolean parameter. Must be `TrueClass` or `FalseClass`.
 
 #### Integer type
 
-Defines an integer parameter. Must be an `Integer`.
+Type `:integer`. Defines an integer parameter. Must be an `Integer`.
 
 #### Float type
 
-Defines a float parameter. Must be a `Float`.
+Type `:float`. Defines a float parameter. Must be a `Float`.
 
 #### Decimal type
 
-Defines a decimal parameter. Must be a `BigDecimal`.
+Type `:decimal`. Defines a decimal parameter. Must be a `BigDecimal`.
 
 #### Number type
 
-Defines a number parameter. Must be either an `Integer`, a `Float`, or a `BigDecimal`.
+Type `:number`. Defines a number parameter. Must be either an `Integer`, a `Float`, or a `BigDecimal`.
 
 #### Symbol type
 
-Defines a symbol parameter. Must be a `Symbol`.
+Type `:symbol`. Defines a symbol parameter. Must be a `Symbol`.
 
 #### Time type
 
-Defines a time parameter. Must be a `Time`.
+Type `:time`. Defines a time parameter. Must be a `Time`.
 
 #### Date type
 
-Defines a time parameter. Must be a `Date`.
+Type `:date`. Defines a date parameter. Must be a `Date`.
 
 ### Non-scalar types
 
@@ -654,7 +700,7 @@ Defines a time parameter. Must be a `Date`.
 
 #### Array type
 
-Defines an array parameter. Must be an `Array`.
+Type `:array`. Defines an array parameter. Must be an `Array`.
 
 Arrays are a special type. They can accept a block that defines its item types,
 which may be a nested schema.
@@ -675,7 +721,7 @@ end
 
 #### Hash type
 
-Defines a hash parameter. Must be a `Hash`.
+Type `:hash`. Defines a hash parameter. Must be a `Hash`.
 
 Hashes are a special type. They can accept a block that defines a nested schema.
 
@@ -721,6 +767,100 @@ TypedParams.types.register(:metadata,
 )
 ```
 
+### Formats
+
+Out of the box, `typed_params` ships with two formatters. Formatters are
+run after all validations and transforms, formatting the params from
+one format to another format.
+
+By default, no formatter is used.
+
+#### JSONAPI format
+
+You can add convenient support for JSONAPI by using the `:jsonapi` format.
+
+All request `data` will be transformed into a hash, useable within models.
+
+In addition, request `meta` will be available inside of the controller
+action with the following methods:
+
+- `#{controller_name.singularize}_meta`
+- `#typed_meta`
+
+```ruby
+class UsersController < ApplicationController
+  typed_params {
+    format :jsonapi
+
+    param :data, type: :hash do
+      param :type, type: :string, inclusion: { in: %w[users user] }, noop: true
+      param :id, type: :string, noop: true
+      param :attributes, type: :hash do
+        param :first_name, type: :string, optional: true
+        param :last_name, type: :string, optional: true
+        param :email, type: :string, format: { with: /@/ }
+        param :password, type: :string
+      end
+      param :relationships, type: :hash do
+        param :team, type: :hash do
+          param :data, type: :hash do
+            param :type, type: :string, inclusion: { in: %w[teams team] }
+            param :id, type: :string
+          end
+        end
+      end
+    end
+
+    param :meta, type: :hash, optional: true do
+      param :affilate_id, type: :string, optional: true
+    end
+  }
+  def create
+    puts user_params
+    # => {
+    #      first_name: 'John',
+    #      last_name: 'Smith',
+    #      email: 'json@smith.example',
+    #      password: '7c84241a1102',
+    #      team_id: '1',
+    #    }
+
+    puts user_meta
+    # => { affilate_id: 'e805' }
+  end
+end
+```
+
+#### Rails format
+
+You can add conventional wrapped params using the `:rails` format.
+
+```ruby
+class UsersController < ApplicationController
+  typed_params {
+    format :rails
+
+    param :first_name, type: :string, optional: true
+    param :last_name, type: :string, optional: true
+    param :email, type: :string, format: { with: /@/ }
+    param :password, type: :string
+    param :team_id, type: :string
+  }
+  def create
+    puts user_params
+    # => {
+    #      user: {
+    #        first_name: 'John',
+    #        last_name: 'Smith',
+    #        email: 'json@smith.example',
+    #        password: '7c84241a1102',
+    #        team_id: '1',
+    #      }
+    #    }
+  end
+end
+```
+
 ## Is it any good?
 
 [Yes.](https://news.ycombinator.com/item?id=3067434)

data/lib/typed_params/controller.rb

@@ -71,8 +71,6 @@ module TypedParams
 
       private
 
-      def typed_namespace = self.class
-
       def respond_to_missing?(method_name, *)
         return super unless
           /_(params|query)\z/.match?(method_name)
@@ -111,7 +109,7 @@ module TypedParams
     class_methods do
       def typed_params(on: nil, schema: nil, format: nil, **kwargs, &)
         schema = case schema
-                 in Array(Symbol, Symbol) => namespace, key
+                 in Array(Symbol => namespace, Symbol => key)
                    typed_schemas[namespace, key] || raise(ArgumentError, "schema does not exist: #{namespace.inspect}/#{key.inspect}")
                  in Symbol => key
                    typed_schemas[self, key] || raise(ArgumentError, "schema does not exist: #{key.inspect}")
@@ -133,7 +131,7 @@ module TypedParams
 
       def typed_query(on: nil, schema: nil, **kwargs, &)
         schema = case schema
-                 in Array(Symbol, Symbol) => namespace, key
+                 in Array(Symbol => namespace, Symbol => key)
                    typed_schemas[namespace, key] || raise(ArgumentError, "schema does not exist: #{namespace.inspect}/#{key.inspect}")
                  in Symbol => key
                    typed_schemas[self, key] || raise(ArgumentError, "schema does not exist: #{key.inspect}")

data/lib/typed_params/parameterizer.rb

@@ -31,9 +31,6 @@ module TypedParams
                 :parent
 
     def parameterize_array_schema(key:, value:)
-      return parameterize_value(key:, value:) unless
-        value.is_a?(Array)
-
       param = Parameter.new(key:, value: [], schema:, parent:)
 
       value.each_with_index do |v, i|
@@ -56,9 +53,6 @@ module TypedParams
     end
 
     def parameterize_hash_schema(key:, value:)
-      return parameterize_value(key:, value:) unless
-        value.is_a?(Hash)
-
       param = Parameter.new(key:, value: {}, schema:, parent:)
 
       value.each do |k, v|

data/lib/typed_params/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedParams
-  VERSION = '0.2.0'
+  VERSION = '1.0.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typed_params
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-07 00:00:00.000000000 Z
+date: 2023-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails