Consistent date and time formatting for the Lesli Framework.
Introduction
LesliDate provides date and time formatting utilities for applications built with the Lesli Framework.
It applies the host application's Lesli date, time-zone, and format configuration while providing compatible SQL expressions for SQLite and PostgreSQL.
Features
- Date, time, and date-time formatting
- Human-readable date and time formats
- Time-zone-aware parsing and output
- ISO 8601 and custom input formats
- SQLite- and PostgreSQL-compatible date expressions
- Database-safe current timestamp helpers
Installation
Requires Ruby 3.3 or later, ActiveSupport and ActiveRecord 8.0.x or 8.1.x, and I18n >= 1.6, < 2. The host application supplies Lesli.config.datetime and its database driver. LesliDate ships no locale data.
Add LesliDate to the application:
bundle add lesli_date
Usage
Format dates and times
Create a formatter from a Date, DateTime, Time, TimeWithZone, supported ISO-style string, or explicitly formatted date string:
datetime = LesliDate::Formatter.new(Time.current)
datetime.date.to_s
datetime.time.to_s
datetime.date_time.to_s
datetime.date_words.to_s
datetime.date_time_words.to_s
Pass the input format when parsing a custom string:
LesliDate::Formatter
.new("2026/07/19 14:30", "%Y/%m/%d %H:%M")
.date_time
.to_s
Calendar inputs retain their day and return a Date from get. Instants return an ActiveSupport::TimeWithZone. Time selectors require an instant.
LesliDate::Formatter.new("2026-10-22").date.to_s
LesliDate::Formatter.new(
"2026-10-22 14:30",
input_zone: "America/Guatemala",
zone: "UTC"
).date_time.to_s
Offset-free date-time strings default to UTC input. Explicit offsets determine the instant. Parsing delegates to Ruby's DateTime.parse and DateTime.strptime, with Rails handling zone conversion. Invalid values or native parsing failures raise LesliDate::ParseError, a subclass of ArgumentError. See Parsing rules for details.
Formats and language
All selectors use their matching pattern in Lesli.config.datetime[:formats], with defaults for omitted or nil values. Output configuration is checked when the formatter is constructed.
to_s uses the translations already loaded by Rails through I18n.localize. It follows the current I18n.locale, or an explicit locale for one formatter:
LesliDate::Formatter.new(value, locale: :es).date_words.to_s
LesliDate ships no translations. Add overrides in Lesli only when customization is desired. See Configuration for the initializer settings, defaults and native Rails localization.
Database compatibility
Generate adapter-compatible SQL for timestamp columns:
formatter = LesliDate::Formatter.new.date_time
formatter.db_timestamps
formatter.db_column("published_at", "articles")
LesliDate::Compatibility.db_now
Both adapters expose created_at_string and updated_at_string. Use db_column(:created_at, as: false) when grouping by an expression. Native SQL formats and zone support differ between adapters; see Database expressions for the supported patterns, SQLite fixed-offset limits, and PostgreSQL zone conversion.
See application examples for form fields, API timestamps, CSV imports and SQL selections. Selectors still mutate the same formatter and return self; input values and configuration are not modified.
Development
Clone the repository and install its dependencies:
git clone https://github.com/LesliTech/LesliDate.git
cd LesliDate
bundle install
To use local source from a Lesli development workspace, reference it from the host application's Gemfile:
gem "lesli_date", path: "gems/LesliDate"
Tests
Run the default test task from the LesliDate directory:
bundle exec rake
The suite uses LesliTesting's standalone gem profile, Minitest, controlled Lesli configuration, a fixed clock, and real SQL queries. SQLite runs in memory by default. To execute the same suite on PostgreSQL, provide a test database URL:
COVERAGE=true bundle exec rake test
LESLI_DATE_DATABASE_URL=postgresql://localhost/lesli_date_test bundle exec rake test
PostgreSQL tests create and clean up an isolated schema. All regressions execute as ordinary tests, including each adapter's native formatting behavior.
CI uses the LesliActions gem workflow for SQLite coverage and packaging, plus Rails 8.0/8.1 jobs that execute queries in SQLite and PostgreSQL 17. See Development and tests for setup and reproducible ordering.
Documentation
- Lesli website
- Documentation
- Installation
- Configuration
- Formatter API
- Parsing rules
- Database expressions
- Application examples
- Changelog
- Release notes
- Issue tracker
- Source code
Community
License
Copyright (c) 2026, Lesli Technologies, S. A.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
The complete license text is available in the license file.
The Open-Source SaaS Development Framework for Ruby on Rails.
Last Update: 2026/10/23