{"id":13483838,"url":"https://github.com/adzap/validates_timeliness","last_synced_at":"2025-04-10T10:48:23.248Z","repository":{"id":417606,"uuid":"37300","full_name":"adzap/validates_timeliness","owner":"adzap","description":"Date and time validation plugin for ActiveModel and Rails.  Supports multiple ORMs and allows custom date/time formats.","archived":false,"fork":false,"pushed_at":"2024-01-04T16:32:41.000Z","size":1375,"stargazers_count":1586,"open_issues_count":24,"forks_count":227,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-10-29T15:55:35.946Z","etag":null,"topics":["activemodel","activerecord","rails","validation"],"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/adzap.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2008-07-25T22:36:22.000Z","updated_at":"2024-10-23T06:51:06.000Z","dependencies_parsed_at":"2024-06-18T12:23:30.326Z","dependency_job_id":"e526c9fe-8399-47b8-bd6e-3a546741bb93","html_url":"https://github.com/adzap/validates_timeliness","commit_stats":{"total_commits":386,"total_committers":29,"mean_commits":"13.310344827586206","dds":"0.10880829015544047","last_synced_commit":"fdff26b1753dbccbdd22dd5fdaf8743f52fabcd6"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzap%2Fvalidates_timeliness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzap%2Fvalidates_timeliness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzap%2Fvalidates_timeliness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzap%2Fvalidates_timeliness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adzap","download_url":"https://codeload.github.com/adzap/validates_timeliness/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248202175,"owners_count":21064281,"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":["activemodel","activerecord","rails","validation"],"created_at":"2024-07-31T17:01:15.789Z","updated_at":"2025-04-10T10:48:23.225Z","avatar_url":"https://github.com/adzap.png","language":"Ruby","funding_links":[],"categories":["Date and Time Processing","Ruby","Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# ValidatesTimeliness [![build](https://github.com/adzap/validates_timeliness/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/adzap/validates_timeliness/actions/workflows/ci.yml)\n\n- Source:  https://github.com/adzap/validates_timeliness\n- Issues:  https://github.com/adzap/validates_timeliness/issues\n\n\n## Description\n\nComplete validation of dates, times and datetimes for Rails 8.x and ActiveModel.\n\nOlder Rails versions:\n\n- Rails 4.x: [https://github.com/adzap/validates_timeliness/tree/4-0-stable]\n- Rails 5.x: [https://github.com/adzap/validates_timeliness/tree/5-0-stable]\n- Rails 6.x: [https://github.com/adzap/validates_timeliness/tree/6-0-stable]\n- Rails 7.x: [https://github.com/adzap/validates_timeliness/tree/7-0-stable]\n\n\n## Features\n\n- Adds validation for dates, times and datetimes to ActiveModel\n- Handles timezones and type casting of values for you\n- Only Rails date/time validation plugin offering complete validation (See ORM/ODM support)\n- Uses extensible date/time parser (Using [timeliness gem](https://github.com/adzap/timeliness). See Plugin Parser)\n- Adds extensions to fix Rails date/time select issues (See Extensions)\n- Supports I18n for the error messages. For multi-language support try [timeliness-i18n gem](https://github.com/pedrofurtado/timeliness-i18n).\n- Supports all the Rubies (that any sane person would be using in production).\n\n\n## Installation\n\nIn Gemfile\n```ruby\ngem 'validates_timeliness', '~\u003e 8.0.0.beta1'\n```\n\nRun bundler:\n```bash\n$ bundle install\n```\n\nThen run\n```bash\n$ rails generate validates_timeliness:install\n```\n\nThis creates configuration initializer and locale files. In the initializer, there are a number of config options to customize the plugin.\n\n**NOTE**: You may wish to enable the plugin parser and the extensions to start.\nPlease read those sections first.\n\n## Examples\n\n```ruby\nvalidates_datetime :occurred_at\n\nvalidates_date :date_of_birth, before: lambda { 18.years.ago },\n                                before_message: \"must be at least 18 years old\"\n\nvalidates_datetime :finish_time, after: :start_time # Method symbol\n\nvalidates_date :booked_at, on: :create, on_or_after: :today # See Restriction Shorthand.\n\nvalidates_time :booked_at, between: ['9:00am', '5:00pm'] # On or after 9:00AM and on or before 5:00PM\nvalidates_time :booked_at, between: '9:00am'..'5:00pm' # The same as previous example\nvalidates_time :booked_at, between: '9:00am'...'5:00pm' # On or after 9:00AM and strictly before 5:00PM\n\nvalidates_time :breakfast_time, on_or_after: '6:00am',\n                                on_or_after_message: 'must be after opening time',\n                                before: :lunchtime,\n                                before_message: 'must be before lunch time'\n```\n\n## Usage\n\nTo validate a model with a date, time or datetime attribute you just use the\nvalidation method:\n\n```ruby\nclass Person \u003c ActiveRecord::Base\n  validates_date :date_of_birth, on_or_before: lambda { Date.current }\n  # or\n  validates :date_of_birth, timeliness: { on_or_before: lambda { Date.current }, type: :date }\nend\n```\n\nor even on a specific record, per ActiveModel API.\n```ruby\n@person.validates_date :date_of_birth, on_or_before: lambda { Date.current }\n```\n\nThe list of validation methods available are as follows:\n- `validates_date`     - validate value as date\n- `validates_time`     - validate value as time only i.e. '12:20pm'\n- `validates_datetime` - validate value as a full date and time\n- `validates`          - use the :timeliness key and set the type in the hash.\n\nThe validation methods take the usual options plus some specific ones to\nrestrict the valid range of dates or times allowed\n\nTemporal options (or restrictions):\n- `:is_at`        - Attribute must be equal to value to be valid\n- `:before`       - Attribute must be before this value to be valid\n- `:on_or_before` - Attribute must be equal to or before this value to be valid\n- `:after`        - Attribute must be after this value to be valid\n- `:on_or_after`  - Attribute must be equal to or after this value to be valid\n- `:between`      - Attribute must be between the values to be valid. Range or Array of 2 values.\n\nRegular validation options:\n- `:allow_nil`    - Allow a nil value to be valid\n- `:allow_blank`  - Allows a nil or empty string value to be valid\n- `:if`           - Execute validation when :if evaluates true\n- `:unless`       - Execute validation when :unless evaluates false\n- `:on`           - Specify validation context e.g :save, :create or :update. Default is :save.\n\nSpecial options:\n- `:ignore_usec`  - Ignores microsecond value on datetime restrictions\n- `:format`       - Limit validation to a single format for special cases. Requires plugin parser.\n\nThe temporal restrictions can take 4 different value types:\n- Date, Time, or DateTime object value\n- Proc or lambda object which may take an optional parameter, being the record object\n- A symbol matching a method name in the model\n- String value\n\n\nWhen an attribute value is compared to temporal restrictions, they are\ncompared as the same type as the validation method type. So using\nvalidates_date means all values are compared as dates.\n\n## Configuration\n\n### ORM/ODM Support\n\nThe plugin adds date/time validation to ActiveModel for any ORM/ODM that\nsupports the ActiveModel validations component. However, there is an issue\nwith most ORM/ODMs which does not allow 100% date/time validation by default.\nSpecifically, when you assign an invalid date/time value to an attribute, most\nORM/ODMs will only store a nil value for the attribute. This causes an issue\nfor date/time validation, since we need to know that a value was assigned but\nwas invalid. To fix this, we need to cache the original invalid value to know\nthat the attribute is not just nil.\n\nEach ORM/ODM requires a specific shim to fix it. The plugin includes a shim\nfor ActiveRecord and Mongoid. You can activate them like so\n```ruby\nValidatesTimeliness.setup do |config|\n  # Extend ORM/ODMs for full support (:active_record).\n  config.extend_orms = [ :active_record ]\nend\n```\n\nBy default the plugin extends ActiveRecord if loaded. If you wish to extend\nanother ORM then look at the [wiki page](https://github.com/adzap/validates_timeliness/wiki/ORM-Support) for more\ninformation.\n\nIt is not required that you use a shim, but you will not catch errors when the\nattribute value is invalid and evaluated to nil.\n\n### Error Messages\n\nUsing the I18n system to define new defaults:\n```yml\nen:\n  errors:\n    messages:\n      invalid_date: \"is not a valid date\"\n      invalid_time: \"is not a valid time\"\n      invalid_datetime: \"is not a valid datetime\"\n      is_at: \"must be at %{restriction}\"\n      before: \"must be before %{restriction}\"\n      on_or_before: \"must be on or before %{restriction}\"\n      after: \"must be after %{restriction}\"\n      on_or_after: \"must be on or after %{restriction}\"\n```\n\nThe `%{restriction}` signifies where the interpolation value for the restriction will be inserted.\n\nYou can also use validation options for custom error messages. The following\noption keys are available:\n```ruby\n:invalid_date_message\n:invalid_time_message\n:invalid_datetime_message\n:is_at_message\n:before_message\n:on_or_before_message\n:after_message\n:on_or_after_message\n```\n\n**Note**: There is no `:between_message` option. The between error message should be\ndefined using the `:on_or_after` and `:on_or_before` (`:before` in case when\n`:between` argument is a `Range` with excluded high value, see Examples) messages.\n\nIt is highly recommended you use the `I18n` system for error messages.\n\n### Plugin Parser\n\nThe plugin uses the [timeliness gem](https://github.com/adzap/timeliness) as a\nfast, configurable and extensible date and time parser. You can add or remove\nvalid formats for `dates`, `times`, and `datetimes`. It is also more strict than the\nRuby parser, which means it won't accept day of the month if it's not a valid\nnumber for the month.\n\nBy default the parser is disabled. To enable it:\n```ruby\n# in the setup block\nconfig.use_plugin_parser = true\n```\n\nEnabling the parser will mean that strings assigned to attributes validated\nwith the plugin will be parsed using the gem. See the\n[wiki](https://github.com/adzap/validates_timeliness/wiki/Plugin-Parser) for\nmore details about the parser configuration.\n\n### Restriction Shorthand\n\nIt is common to restrict an attribute to being on or before the current time\nor current day. To specify this you need to use a lambda as an option value\ne.g. `lambda { Time.current }`. This can be tedious noise amongst your\nvalidations for something so common. To combat this the plugin allows you to\nuse shorthand symbols for often used relative times or dates.\n\nJust provide the symbol as the option value like so:\n```ruby\nvalidates_date :birth_date, on_or_before: :today\n```\n\nThe `:today` symbol is evaluated as `lambda { Date.current }`. The `:now` and\n`:today` symbols are pre-configured. Configure your own like so:\n```ruby\n# in the setup block\nconfig.restriction_shorthand_symbols.update(yesterday: lambda { 1.day.ago })\n```\n\n### Default Timezone\n\nThe plugin needs to know the default timezone you are using when parsing or\ntype casting values. If you are using ActiveRecord then the default is\nautomatically set to the same default zone as ActiveRecord. If you are using\nanother ORM you may need to change this setting.\n```ruby\n# in the setup block\nconfig.default_timezone = :utc\n```\n\nBy default it will be `UTC` if ActiveRecord is not loaded.\n\n### Dummy Date For Time Types\n\nGiven that Ruby has no support for a time-only type, all time type columns are\nevaluated as a regular Time class objects with a dummy date value set. Rails\ndefines the dummy date as 2000-01-01. So a time of '12:30' is evaluated as a\nTime value of '2000-01-01 12:30'. If you need to customize this for some\nreason you can do so as follows:\n```ruby\n# in the setup block\nconfig.dummy_date_for_time_type = [2009, 1, 1]\n```\n\nThe value should be an array of 3 values being year, month and day in that order.\n\n### Temporal Restriction Errors\n\nWhen using the validation temporal restrictions there are times when the\nrestriction option value itself may be invalid. This will add an error to the\nmodel such as 'Error occurred validating birth_date for :before restriction'.\nThese can be annoying in development or production as you most likely just\nwant to skip the option if no valid value was returned. By default these\nerrors are displayed in Rails test mode.\n\nTo turn them on/off:\n```ruby\n# in the setup block\nconfig.ignore_restriction_errors = true\n```\n\n## Extensions\n\n### Strict Parsing for Select Helpers\n\nWhen using date/time select helpers, the component values are handled by\nActiveRecord using the Time class to instantiate them into a time value. This\nmeans that some invalid dates, such as 31st June, are shifted forward and\ntreated as valid. To handle these cases in a strict way, you can enable the\nplugin extension to treat them as invalid dates.\n\nTo activate it, uncomment this line in the initializer:\n```ruby\n# in the setup block\nconfig.enable_multiparameter_extension!\n```\n\n### Display Invalid Values in Select Helpers\n\nThe plugin offers an extension for ActionView to allowing invalid date and\ntime values to be redisplayed to the user as feedback, instead of a blank\nfield which happens by default in Rails. Though the date helpers make this a\npretty rare occurrence, given the select dropdowns for each date/time\ncomponent, but it may be something of interest.\n\nTo activate it, uncomment this line in the initializer:\n```ruby\n# in the setup block\nconfig.enable_date_time_select_extension!\n```\n\n## Contributors\n\nTo see the generous people who have contributed code, take a look at the\n[contributors list](https://github.com/adzap/validates_timeliness/contributors).\n\n## Maintainers\n\n* [Adam Meehan](https://github.com/adzap)\n\n## License\n\nCopyright (c) 2021 Adam Meehan, released under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzap%2Fvalidates_timeliness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadzap%2Fvalidates_timeliness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzap%2Fvalidates_timeliness/lists"}