LesliDate

Consistent date and time formatting for the Lesli Framework.


LesliDate test status Gem Version Codecov Sonar Quality Gate




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


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.




Lesli icon

The Open-Source SaaS Development Framework for Ruby on Rails.

 Edit this page

Last Update: 2026/10/23