{"id":21519325,"url":"https://github.com/alexwayfer/formalism","last_synced_at":"2025-04-09T22:08:42.713Z","repository":{"id":39657647,"uuid":"131032392","full_name":"AlexWayfer/formalism","owner":"AlexWayfer","description":"Ruby gem for forms with validations and nesting.","archived":false,"fork":false,"pushed_at":"2025-04-04T12:46:09.000Z","size":347,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T22:08:36.036Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexWayfer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-25T16:10:37.000Z","updated_at":"2025-01-06T00:24:03.000Z","dependencies_parsed_at":"2023-02-13T22:00:34.366Z","dependency_job_id":"e4d089c3-eb64-47e3-bb92-aad97ce0f144","html_url":"https://github.com/AlexWayfer/formalism","commit_stats":{"total_commits":242,"total_committers":4,"mean_commits":60.5,"dds":"0.29338842975206614","last_synced_commit":"a01daf5a9d4b274d3a290aac46f7c1c1107f7f57"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexWayfer%2Fformalism","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexWayfer%2Fformalism/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexWayfer%2Fformalism/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexWayfer%2Fformalism/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexWayfer","download_url":"https://codeload.github.com/AlexWayfer/formalism/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119294,"owners_count":21050755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T00:57:27.044Z","updated_at":"2025-04-09T22:08:42.690Z","avatar_url":"https://github.com/AlexWayfer.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Formalism\n\n[![Cirrus CI - Base Branch Build Status](https://img.shields.io/cirrus/github/AlexWayfer/formalism?style=flat-square)](https://cirrus-ci.com/github/AlexWayfer/formalism)\n[![Codecov branch](https://img.shields.io/codecov/c/github/AlexWayfer/formalism/main.svg?style=flat-square)](https://codecov.io/gh/AlexWayfer/formalism)\n[![Code Climate](https://img.shields.io/codeclimate/maintainability/AlexWayfer/formalism.svg?style=flat-square)](https://codeclimate.com/github/AlexWayfer/formalism)\n[![Depfu](https://img.shields.io/depfu/AlexWayfer/benchmark_toys?style=flat-square)](https://depfu.com/repos/github/AlexWayfer/formalism)\n[![Inline docs](https://inch-ci.org/github/AlexWayfer/formalism.svg?branch=main)](https://inch-ci.org/github/AlexWayfer/formalism)\n[![license](https://img.shields.io/github/license/AlexWayfer/formalism.svg?style=flat-square)](https://github.com/AlexWayfer/formalism/blob/main/LICENSE.txt)\n[![Gem](https://img.shields.io/gem/v/formalism.svg?style=flat-square)](https://rubygems.org/gems/formalism)\n\nRuby gem for forms with validations and nesting.\n\n## Why\n\nI need for service-like objects.\n\nI've explored these projects:\n\n*   [Reform](https://github.com/trailblazer/reform)\n*   [Mutations](https://github.com/cypriss/mutations)\n*   [Interactor](https://github.com/collectiveidea/interactor)\n*   [dry-rb](https://github.com/dry-rb)\n\nBut nothing of them supports all features I need for:\n\n*   nesting (into unlimited levels) of themselves;\n*   simple syntax;\n*   custom validations and coercions;\n*   unified output.\n\nSo, I've tried to combine these all into one library and got Formalism.\n\n### Why here are forms and what about service objects?\n\nI've discovered that form object, only with validations,\nare useless without service objects. So, I've combined them:\nservice objects include validations.\n\n### If these are service objects, why they called forms?\n\nBecause if we're combining them — it's more like forms with logic inside for me\nthan service objects built-in forms. Even in HTML we're writing `\u003cform\u003e`.\nSo, Formalism can accept all data from any-difficult `\u003cform\u003e` and process it,\nalso with nested forms (for example, if you have some request form\nwith contact data and want to pass contacts into something like user form).\n\n### And if I need for simple service object without validation?\n\nYou can use `Formalism::Action`, a parent of `Formalism::Form`.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'formalism'\n```\n\nAnd then execute:\n\n```shell\nbundle install\n```\n\nOr install it yourself as:\n\n```shell\ngem install formalism\n```\n\n## Usage\n\n### Basic example\n\n```ruby\nclass FindArtistForm \u003c Formalism::Form\n  field :name\n\n  private\n\n  def validate\n    if name.to_s.empty?\n      errors.add 'Name is not provided'\n    end\n  end\n\n  def execute\n    Artist.first(fields_and_nested_forms)\n  end\nend\n\nclass CreateAlbumForm \u003c Formalism::Form\n  field :name, String\n  fiels :tags, Array, of: String\n  nested :artist, FindArtistForm\n\n  private\n\n  def validate\n    if name.to_s.empty?\n      errors.add 'Name is not provided'\n    end\n  end\n\n  def execute\n    Album.create(fields_and_nested_forms)\n  end\nend\n\nform = CreateAlbumForm.new(\n  name: 'Hits', tags: %w[Indie Rock Hits], artist: { name: 'Alex' }\n)\nform.run\n```\n\n### Running\n\nUsually you need to initialize a form and execute `#run` method.\nInternally, it runs `#valid?` (public) and `#execute` (private) methods.\n`#valid?` runs `#validate` (private) of a form itself and nested forms.\n`#run` can be redefined for database transaction, for example.\n\nAlso you can call `.run` with arguments for `#initialize`,\nit's the alias for `#initialize` + `#run`.\n\n#### Form outcome\n\nAny call of `run` returns `Form::Outcome` instance which has `#success?`,\n`#result` and `#errors` methods. Result is a result of `#execute` method.\nBe careful: calling `#result` for failed outcome will raise `ValidationError`.\n\n### Field type\n\nField receives type as the second argument.\nIt's not required.\nIt can be a constant, String or Symbol.\nIf specified — there is a coercion to specified type,\nif not — data remains unchanged.\n\nNested forms — their class, as constant.\nType or `:initialize` block is required.\n\nFormalism also supports `Array` type with the optional `:of` option\n(type of elements).\nCoercion will be applied to a data itself and to its elements.\n\n#### Coercion\n\nThere is built-in coercion into some types, if you try to coerce\nto undefined type — you'll get `Formalism::Form::NoCoercionError`.\n\nYou can define a coercion to some type via definition of such class:\n\n```ruby\n# frozen_string_literal: true\n\nmodule Formalism\n  class Form \u003c Action\n    class Coercion\n      ## Class for coercion to String\n      class String \u003c Base\n        private\n\n        def execute\n          @value\u0026.to_s\n        end\n      end\n    end\n  end\nend\n```\n\n### Default value\n\n`field` and `nested` accepts `:default` option.\nIt can be any value, if it's an instance of `Proc` — it'll be executed\nin the form instance scope.\n\n### Different keys\n\n`field` supports `:key` option (Symbol) to receive data by a different key,\nnot as a field name.\n\n### Custom initialization of nested forms\n\nBy default, nested forms initialized with data by key as their name\nin parent data. So, if a parent receive `{ foo: 1, bar: { baz: 2 } }`,\nit's nested form `:bar` will receive `{ baz: 2 }`.\n\nIf you want to prevent initialization at all, or pass custom arguments —\nyou should use `:initialize` option which accepts a proc\nwith a form class argument.\n\nIf you want to just refine incoming data (add or remove) — you should define\n`#params_for_nested_*` private method, where `*` is a nested form name.\nYou can use `super` inside.\n\n### Order of filling with data\n\nFields and nested forms are filling in order of their definition.\nBut sometimes you want to change this order, for example,\nif you have a nested forms in ancestors which depends on data in children forms.\nFor such cases you can use `:depends_on` option, which accepts fields\nand nested forms names as Symbol or Array of symbols. They will be filled\n(and initialized) before dependent.\n\n### Merging into final data\n\nThere is `Form#fields_and_nested_forms` as final data\n(after coercion, defaults, etc). But you may want to not include some fields\nor nested forms into this data. You can do it via `:merge` option,\nwhich can be `true`, `false` or `Proc` (executed in form's instance scope).\n\nFor example:\n\n```ruby\nfield :bar, merge: true\nnested :only_valid, nested_form_class, merge: -\u003e(form) { form.valid? }\n```\n\n### Runnable\n\nYou can disable `#valid?` and `#run` of forms (including nested ones)\nby setting `form.runnable = false`.\nIt can be helpful for some cases, for example, with policies (permissions):\n\n```ruby\ndef initialize_nested_form(name, options)\n  return unless (form = super)\n\n  form.runnable = allowed_to_change?(name)\n  form\nend\n```\n\n### Inheritance\n\nAny `class ChildForm \u003c ParentForm` will have all fields and nested forms\nfrom `ParentForm`.\n\n#### Removing (inherited) field\n\nBut you're able to remove (usually inherited) fields by:\n\n```ruby\nclass ChildForm \u003c ParentForm\n  remove_field :field_from_parent\nend\n```\n\n#### Modules\n\nYou can define modules and use them later like this:\n\n```ruby\nmodule CommonFields\n  include Formalism::Form::Fields\n\n  field :base_field\n  nested :base_nested\nend\n\nclass SomeForm \u003c Formalism::Form\n  include CommonFields\n\n  field :another_field\nend\n```\n\n### Convert to params\n\nYou can convert a Form back to (processed) params, for example, for view render:\n\n```ruby\nform = CreateAlbumForm.new(\n  name: 'Hits', tags: %w[Indie Rock Hits], artist: { name: 'Alex' }\n)\n\nform.to_params\n# {\n#   name: 'Hits',\n#   tags: %w[Indie Rock Hits],\n#   artist: { name: 'Alex' }\n# }\n```\n\n### Actions\n\nFor actions without fields, nesting and validation you can use\n`Formalism::Action` (the parent of `Formalism::Form`).\n\n\n### Plugins\n\nThere is a few plugins which I personally need for:\n\n*   [`formalism-model_forms`](https://github.com/AlexWayfer/formalism-model_forms)\n    Default CRUD forms for [Sequel](https://sequel.jeremyevans.net/) DB models.\n    Can be renamed!\n\n*   [`formalism-sequel_transactions`](https://github.com/AlexWayfer/formalism-sequel_transactions)\n    [Sequel](https://sequel.jeremyevans.net/) transactions inside forms.\n\n*   [`formalism-r18n_errors`](https://github.com/AlexWayfer/formalism-r18n_errors)\n    [R18n](https://github.com/r18n/r18n) errors inside forms, including validation helpers.\n    Can be separated!\n\n## Development\n\nAfter checking out the repo, run `bundle install` to install dependencies.\n\nThen, run `toys rspec` to run the tests.\n\nTo install this gem onto your local machine, run `toys gem install`.\n\nTo release a new version, run `toys gem release %version%`.\nSee how it works [here](https://github.com/AlexWayfer/gem_toys#release).\n\n## Contributing\n\nBug reports and pull requests are welcome on [GitHub](https://github.com/AlexWayfer/formalism).\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwayfer%2Fformalism","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexwayfer%2Fformalism","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwayfer%2Fformalism/lists"}