declare_schema 4.0.2 → 4.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3db1e6df4c65a27e4bd67f67792713c59ff42daa35a210046e1f3bb2e970162
-  data.tar.gz: 1f8ac6833eb61da99b86ded414b2c551296f045e238efc09cfc43ca2a6ac0812
+  metadata.gz: 67a8ff59b5f29818efd240f2d5b07d3631f54c21bf7c0b983c045fa2b6f2d4ac
+  data.tar.gz: cf0ddc6128d5f0e2e3f0d867c3a384942ce35c561f38a35ca58090369c0ab25f
 SHA512:
-  metadata.gz: 99f97e8dc9a8819af6ef940cab00fe23a0f25c04db0beb2e463c64fadee1b8618c0410c210088e702d05f70855b3a0f8659a2dd10288f13ed5ef3eefb42b4538
-  data.tar.gz: 875a01a7b75ef5dc1cc4d4025b903cd2c0ab14ab901758fd183594a0db6c67b673357243e71efc1a1bdacb12676ee35ad226100daf10f9877155580f686b2f16
+  metadata.gz: edb10d4c1b0018a198007a8a9862455991e62df80e786b141a870ac998ed7f2dc7653cbdff14bab4615649fbe45d9caa3be1f3c8ae420f863f28c6ba09b2a06b
+  data.tar.gz: 2b916bf151cbf69d55c52f071fc4a6006e1906e918231ae4f973982034fcae35af3da1b05f19174a741f9461e47998d1c0cd8cdd30e9b88ef0a30f6e6c20109a

data/CHANGELOG.md

@@ -4,6 +4,10 @@ Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.3] - 2026-07-01
+### Changed
+- Documented the `field` DSL macro and the underlying `declare_field` class method.
+
 ## [4.0.2] - 2026-05-29
 ### Fixed
 - Fixed Rails 7.2 compatibility for the `serialize:` field option. Rails 7.2 changed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    declare_schema (4.0.2)
+    declare_schema (4.0.3)
       rails (>= 7.0)
 
 GEM

data/README.md

@@ -89,6 +89,75 @@ create_table :companies, id: :bigint do |t|
     ...
 end
 ```
+### The `field` Macro
+Every `t.<type> :<column_name>, <options>` declaration shown above is syntactic sugar for calling the `field` macro directly:
+```ruby
+create_table :companies, id: :bigint do |t|
+  t.field :company_name, :string, null: false, limit: 100
+    ...
+end
+```
+`field(name, type, *flags, **options)` is the primitive method underlying every typed shorthand (`t.string`, `t.integer`, etc.), as well as the `timestamps` and `optimistic_lock` helpers. A call like `t.string :company_name, limit: 100` is dispatched (via `method_missing`) to `t.field :company_name, :string, limit: 100`.
+
+`field` only exists inside the `declare_schema do ... end` block, but within it, it can be called either with an explicit `t.` receiver (`t.field ...`) or bare (`field ...`), since the block is `instance_eval`'d against the DSL object -- both forms are equivalent. `field` cannot be called outside of the `declare_schema do ... end` block.
+
+Calling `field` directly is useful when you need to dynamically declare field(s) based on meta-data that is available at runtime:
+```ruby
+declare_schema do
+  [[:company_name, :string, { limit: 100 }], [:employee_count, :integer, {}]].each do |name, type, options|
+    field name, type, **options
+  end
+end
+```
+
+#### `:required` and `:unique` Flags
+In addition to keyword options, `field` (and by extension, `t.<type>`) accepts optional positional flags placed immediately after the column name:
+- `:required` - adds `validates_presence_of :<column_name>` to the model.
+- `:unique` - adds `validates_uniqueness_of :<column_name>, allow_nil: <true unless :required is also given>` to the model.
+
+For example:
+```ruby
+declare_schema do
+  string :title, :required, limit: 255
+  string :slug,  :unique,   limit: 255
+end
+```
+is equivalent to:
+```ruby
+declare_schema do
+  field :title, :string, :required, limit: 255
+  field :slug,  :string, :unique,   limit: 255
+end
+```
+
+#### Calling `declare_field` outside the block
+`field` is DSL sugar that simply calls the model's `declare_field` class method: `field(name, type, *flags, **options)` calls `declare_field(name, type, *flags, **options)`. Unlike `field`, `declare_field` is a regular class method, so it can be called directly on the model outside of a `declare_schema do ... end` block, e.g. from a shared concern that adds a field to any model that includes it:
+```ruby
+module SoftDeletable
+  extend ActiveSupport::Concern
+
+  included do
+    declare_schema { }
+    declare_field :title, :string, :required, limit: 255
+    declare_field :slug,  :string, :unique,   limit: 255
+  end
+end
+```
+which is equivalent to:
+```ruby
+module SoftDeletable
+  extend ActiveSupport::Concern
+
+  included do
+    declare_schema do
+      field :title, :string, :required, limit: 255
+      field :slug,  :string, :unique,   limit: 255
+    end
+  end
+end
+```
+**Note:** `declare_field` is only defined once `declare_schema` has been called at least once on the model (even with no block, e.g. bare `declare_schema`), since that's what mixes in the `DeclareSchema` class methods.
+
 ### Field (Column) Types
 All of the ActiveRecord field types are supported, as returned by the database driver in use at the time.
 These typically include:

data/lib/declare_schema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeclareSchema
-  VERSION = "4.0.2"
+  VERSION = "4.0.3"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: declare_schema
 version: !ruby/object:Gem::Version
-  version: 4.0.2
+  version: 4.0.3
 platform: ruby
 authors:
 - Invoca Development adapted from hobo_fields by Tom Locke
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -144,7 +143,6 @@ homepage: https://github.com/Invoca/declare_schema
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -159,8 +157,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Database schema declaration and migration generator for Rails
 test_files: []