clojure.java-time
A Clojure wrapper for the Java 8 Date-Time API providing a consistent, idiomatic interface for date and time operations.
What is clojure.java-time?
Clojure.Java-Time is a Clojure library that provides an idiomatic wrapper around the Java 8 Date-Time API (java.time). It simplifies working with dates, times, zones, and periods in Clojure by offering a consistent, functional interface that reduces the need for verbose Java interop. The library addresses the complexity of the native Java Time API by exposing it through a single, well-organized namespace.
Clojure developers on the JVM who need to handle date and time operations, especially those migrating from Joda-Time or clj-time, or starting new projects with Java 8+.
Developers choose Clojure.Java-Time for its clean, idiomatic Clojure API that fully leverages the modern Java Time API without requiring extensive Java interop. It offers a seamless alternative to older libraries like clj-time, with better design and no dependency on Joda-Time.
Overview
Java 8 Date-Time API for Clojure
Use Cases
Best For
- Clojure applications requiring modern date-time handling with Java 8+
- Migrating from Joda-Time or clj-time to the Java Time API
- Projects needing consistent date-time operations across different types (LocalDate, ZonedDateTime, etc.)
- Applications that interact with legacy Java date types (java.util.Date, java.sql.*)
- Testing time-dependent logic with mock clocks
- Simplifying Java interop when working with dates and times in Clojure
Not Ideal For
- Projects targeting both JVM and JavaScript runtimes (e.g., ClojureScript)
- Applications requiring guaranteed low-latency date-time construction without manual warm-up
- Teams already using cljc.java-time or tick for cross-platform compatibility or richer APIs
- Simple scripts where direct Java interop is sufficient and a library adds unnecessary overhead
Pros & Cons
Pros
Provides a single namespace (`java-time.api`) with consistent functions for all Java Time types, eliminating verbose Java interop and reducing cognitive load.
Supports conversions to and from legacy Java date types (e.g., java.util.Date, java.sql.*) and Joda-Time, easing migration from older systems.
Includes a mock clock system via `mock-clock` and `with-clock`, enabling controlled time manipulation for reliable unit tests.
Adds a property system for uniform querying and modification of temporal fields, enhancing flexibility beyond Java's static API.
Cons
First calls to constructors are slow due to conversion graph pathfinding, requiring manual warm-up for predictable latency in production code, as admitted in the README.
Limited to JVM platforms, making it unsuitable for ClojureScript or other non-JVM Clojure implementations, unlike alternatives like cljc.java-time.
The underlying conversion graph can lead to nonsensical results and is difficult to debug or modify, as noted in the implementation details section.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.