Skip to content

Commit

Permalink
improve rationale
Browse files Browse the repository at this point in the history
  • Loading branch information
@henryw374
henryw374 committed Mar 5, 2024
1 parent 91515ad commit b925cf1
Show file tree
Hide file tree
Showing 6 changed files with 125 additions and 119 deletions.
104 changes: 66 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,43 +7,49 @@

zero-dependency, cross-platform Clojure time library

*Status* - pre-alpha.
*Status* - pre-alpha.

* The underlying [Javascript platform time API](https://github.com/tc39/proposal-temporal) has semi-stabilized at ecma `stage 3` - meaning implementors
can still suggest changes. When it has reached `stage 4`, application developers targeting the browser will need to include their own
script to bring in a polyfill if the end-user's browser does not yet have the platform API required.
* The underlying [Javascript platform time API](https://github.com/tc39/proposal-temporal) has semi-stabilized at
ecma `stage 3` - meaning implementors
can still suggest changes. When it has reached `stage 4`, application developers targeting the browser will need to
include their own
script to bring in a polyfill if the end-user's browser does not yet have the platform API required.

## About

* Zero dependency => platform APIs only - see [comparison of java.time vs temporal](https://widdindustries.com/ecma-temporal-vs-java-time/)
* Zero dependency => platform APIs only -
see [comparison of java.time vs temporal](https://widdindustries.com/ecma-temporal-vs-java-time/)
* platform+performance friendly - max DCE-ability for cljs, reflection-free on jvm.
* explicitly named conversions from type to type. no keyword arguments in functions
* no implicit/contextual use of ambient zone or clock
* API based on mnemonics
* small feature set - aim for 80% of everyday date/time use cases.
* assume ISO8601 calendar.
* assume ISO8601 calendar.
* data-literals - same ones as [time-literals](https://github.com/henryw374/time-literals)

### java.time vs Temporal

java.time and Temporal have some shared concepts and some unshared. Naming is also partially shared. [See here for a brief introduction and overview](https://widdindustries.com/blog/ecma-temporal-vs-java-time.html)
java.time and Temporal have some shared concepts and some unshared. Naming is also partially
shared. [See here for a brief introduction and overview](https://widdindustries.com/blog/ecma-temporal-vs-java-time.html)

The below graph shows the entities in Temporal. If you know java.time and you squint a bit, it will look familiar to you.
The below graph shows the entities in Temporal. If you know java.time and you squint a bit, it will look familiar to
you.

![graph of entities in Temporal](https://tc39.es/proposal-temporal/docs/object-model.svg)

Tempo tries to find obvious common ground between java.time and Temporal. Following is some more detail:

*just java.time*

* parsing non-iso strings ([Temporal may have this in the future](https://github.com/js-temporal/proposal-temporal-v2/issues/2))
* parsing non-iso
strings ([Temporal may have this in the future](https://github.com/js-temporal/proposal-temporal-v2/issues/2))
* 2 types to represent temporal-amounts: `Duration` and `Period`
* clojure `=` and `hash` work - so these are added to Temporal objects in Tempo
* fixed & offset clocks - so these are added in cljs Tempo
* OffsetDateTime, OffsetTime, Month, Year and DayOfWeek entities
* Tempo adds DayOfWeek to cljs, so there is e.g. `t/weekday-saturday`
* OffsetDateTime & OffsetTime are not in Tempo
* Month and Year are just represented by integers in Tempo
* OffsetDateTime, OffsetTime, Month, Year and DayOfWeek entities
* Tempo adds DayOfWeek to cljs, so there is e.g. `t/weekday-saturday`
* OffsetDateTime & OffsetTime are not in Tempo
* Month and Year are just represented by integers in Tempo

*just temporal*

Expand All @@ -58,56 +64,74 @@ Tempo tries to find obvious common ground between java.time and Temporal. Follow
## Rationale

Since it was introduced in Java 8, use of the java.time API has become more and more widespread because:
* it improves on the legacy `java.util.Date` API
* it is a platform API - developers and library authors can be confident that other developers will know the API and be happy to use it.

* it improves on the legacy `java.util.Date` API
* it is a platform API - developers and library authors can be confident that other developers will know the API and be
happy to use it.

The same benefits will apply to the Temporal API when it is widely available in browsers.

Cross-platform date/time APIs for Clojure have already proven popular. It seems logical that one should exist targeting both java.time and Temporal.
Cross-platform date/time APIs for Clojure have already proven popular. It seems logical that one should exist targeting
both java.time and Temporal.

However, as stated above, although there is not a 1-1 correspondance between java.time and Temporal, there is sufficient overlap for a cross platform API that covers the majority of everyday use-cases.
However, as stated above, although there is not a 1-1 correspondance between java.time and Temporal, there is sufficient
overlap for a cross platform API that covers the majority of everyday use-cases.

### Why not 'fill in the gaps' to make Temporal like java.time?

There are some obvious benefits to be had if this were done.
There are some obvious benefits to be had if this were done.

However, aside from being a lot of work to do this, Temporal is a different API from java.time. The Temporal authors have designed it from scratch very deliberately and in so doing have made some different choices from java.time.
However, aside from being a lot of work to do this, Temporal is a different API from java.time. The Temporal authors
have designed it from scratch very deliberately and in so doing have made some different choices from java.time.

Where Temporal and java.time overlap, there is obvious scope for a common API. Where they differ, application developers can decide on a case by case basis how to tackle that.
Where Temporal and java.time overlap, there is obvious scope for a common API. Where they differ, application developers
can decide on a case by case basis how to tackle that.

### What about Existing Cross-platform date/time APIs?

[Tick](https://github.com/juxt/tick) (which I help maintain) is great for application developers who want a
[Tick](https://github.com/juxt/tick) (which I help maintain) is great for application developers who want a
cross-platform date-time library based on the java.time API. Tick provides much useful functionality
on top of java.time, but users know they can always drop to [cljc.java-time](https://github.com/henryw374/cljc.java-time),
on top of java.time, but users know they can always drop
to [cljc.java-time](https://github.com/henryw374/cljc.java-time),
to access the full java.time API directly when needed.

Even when Temporal is widely available, I would imagine many Clojure developers will want to keep using Tick because
* It is based on the same java.time API in both JVM and Javascript environments - so the full capability of java.time is available as required.
* The additional build size of Tick in Javascript [does not degrade application performance](https://widdindustries.com/blog/clojurescript-datetime-lib-comparison.html)
Even when Temporal is widely available, I would imagine many Clojure developers will want to keep using Tick because

* It is based on the same java.time API in both JVM and Javascript environments - so the full capability of java.time is
available as required.
* The additional build size of Tick in
Javascript [does not degrade application performance](https://widdindustries.com/blog/clojurescript-datetime-lib-comparison.html)
* Switching away from it will require significant time investment

Since `tick` is based on `java.time`, in its entirety it is incompatible with Temporal. Having said that a `tempo.tick` namespace exists which contains a subset of the functions from `tick.core` which are compatible.
Since `tick` is based on `java.time`, in its entirety it is incompatible with Temporal. Having said that a `tempo.tick`
namespace exists which contains a subset of the functions from `tick.core` which are compatible.

## Usage

### Depend
### Depend

There is no tempo maven artifact atm.

Depend on tempo via deps.edn:

```clojure
{:deps {com.widdindustries/tempo {:git/url "https://github.com/henryw374/tempo.git"
:sha "abc"
}}}
{:deps {com.widdindustries/tempo
{:git/url "https://github.com/henryw374/tempo.git"
:sha "abc"}
; to get data-literals for java.time and Temporal, also add...
com.widdindustries/time-literals-tempo {:mvn/version "0.1.10"}}}
```

### Setup

```clojure
(ns my.cljc.namespace
(:require [com.widdindustries.tempo :as t]))
(:require [com.widdindustries.tempo :as t]
[time-literals.read-write]))

; optionally, print objects as data-literals
(time-literals.read-write/print-time-literals-clj!)
(time-literals.read-write/print-time-literals-cljs!)

;optional - make clojure.core fns =,sort,compare etc work for all js/Temporal entities
(t/extend-all-cljs-protocols)
Expand Down Expand Up @@ -150,7 +174,8 @@ a clock is then passed as arg to all `now` functions, for example:
(t/timezone-now clock)
```

Where a timezone is accessed from an object, or passed into an object, only the string representation is used, referred to as `timezone_id`. Call `str` on a timezone to get its id.
Where a timezone is accessed from an object, or passed into an object, only the string representation is used, referred
to as `timezone_id`. Call `str` on a timezone to get its id.

```clojure
(t/zdt->timezone_id zdt)
Expand Down Expand Up @@ -186,7 +211,7 @@ Where a timezone is accessed from an object, or passed into an object, only the

```

#### Manipulation
#### Manipulation

aka construction a new temporal from one of the same type

Expand All @@ -213,22 +238,25 @@ Consider the following:
(t/<< 1 t/months-property)))
```

If you shift a date forward by an amount, then back by that amount then one might think the output would be equal to the input. In some cases that would happen, but not in the case shown above.
If you shift a date forward by an amount, then back by that amount then one might think the output would be equal to the
input. In some cases that would happen, but not in the case shown above.

Here's a similar example:

```clojure
(let [start (t/date-parse "2020-02-29")]
(-> start
(-> start
(t/with 2021 t/years-property)
(t/with 2020 t/years-property)))
```

We increment the year, then decrement it, but the output is not the same as the input.

Both java.time and Temporal work this way and in my experience it is a source of bugs. For this reason, shifting `>>/<<` and `with` do not work in Tempo if the property is years or months.
Both java.time and Temporal work this way and in my experience it is a source of bugs. For this reason, shifting `>>/<<`
and `with` do not work in Tempo if the property is years or months.

As a safer alternative, I suggest getting the year-month from a temporal first, doing whatever with/shift operations you like then setting the remaining fields.
As a safer alternative, I suggest getting the year-month from a temporal first, doing whatever with/shift operations you
like then setting the remaining fields.

If you do not wish to have this guardrail, set `t/*block-non-commutative-operations*` to false

Expand Down Expand Up @@ -280,7 +308,7 @@ It is preferred to use numbers and properties for example
(t/>> a-date 1 t/days-property)
```

## Dev
## Dev

see dev.clj for instructions

30 changes: 18 additions & 12 deletions deps.edn
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
; this is not the deps for a lib user to depend on. find those under 'gen-out'
{:paths ["src"]
:aliases {:dev {:extra-paths ["dev" "web-target" "test"]
:extra-deps {;ring/ring-core {:mvn/version "1.8.1"}
henryw374/defoclock {:mvn/version "0.1.3"}
backtick/backtick {:mvn/version "0.3.4"}
camel-snake-kebab/camel-snake-kebab {:mvn/version "0.4.2"}
medley/medley {:mvn/version "1.4.0"}
com.widdindustries/tiado-cljs2 {:git/url "https://github.com/henryw374/tiado-cljs2.git" :git/sha "3229283d825a393008a1f1c408603dff775e87c2"}
org.clojure/tools.namespace {:mvn/version "1.4.4"}
babashka/fs {:mvn/version "0.5.20"}
:aliases {:dev {:extra-paths ["dev" "web-target" "test"]
:extra-deps {;ring/ring-core {:mvn/version "1.8.1"}
henryw374/defoclock {:mvn/version "0.1.3"}
backtick/backtick {:mvn/version "0.3.4"}
camel-snake-kebab/camel-snake-kebab {:mvn/version "0.4.2"}
medley/medley {:mvn/version "1.4.0"}
com.widdindustries/tiado-cljs2 {:git/url "https://github.com/henryw374/tiado-cljs2.git" :git/sha "3229283d825a393008a1f1c408603dff775e87c2"}
org.clojure/tools.namespace {:mvn/version "1.4.4"}
babashka/fs {:mvn/version "0.5.20"}
com.widdindustries/time-literals-tempo {:mvn/version "0.1.10"}

}
}
}}
:release {:extra-deps {applied-science/deps-library {:mvn/version "RELEASE"}}
:main-opts ["-m" "applied-science.deps-library"]}


:release {:extra-deps {applied-science/deps-library {:mvn/version "RELEASE"}}
:main-opts ["-m" "applied-science.deps-library"]}
}

}
6 changes: 5 additions & 1 deletion dev/dev.clj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,11 @@
</head>
<body>
<script src=\"/temporal.js\"></script>
<script>
if(!window.Temporal){
document.write('<script src=\"https://tc39.es/proposal-temporal/docs/playground.js\"></script>');
}
</script>
<script src=\"/browser-test/js/test.js\">
</script>
Expand Down
1 change: 1 addition & 0 deletions dev/user.clj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@

(comment
(dev)

)
58 changes: 2 additions & 56 deletions test/com/widdindustries/demo.cljc
View file
Original file line number Diff line number Diff line change
@@ -1,64 +1,10 @@
(ns com.widdindustries.demo
(:require [com.widdindustries.tempo :as t]
;[com.widdindustries.tempo.cljs-protocols :as cljs-protocols]
; [com.widdindustries.tempo.js-temporal-entities :as entities]
; [com.widdindustries.tempo.js-temporal-methods :as methods]
; [com.widdindustries.tempo.clock :as clock]

))

(comment

(t/date-now)
;(t/date-now clock)
(t/date-parse "2020-02-02") ;iso strings only
;(t/date-from {:year 2020 :month 2 :day-of-month 2})
; the -from functions accept a map of components which is sufficient to build the entity
(t/datetime-from {:date (t/date-parse "2020-02-02") :time (t/time-now)})
; or equivalently
(t/datetime-from {:year 2020 :month 2 :day 2 :time (t/time-now)})
; with -from, you can use smaller or larger components.
; larger ones take precedence. below, the :year is ignored, because the :date took precedence (being larger)
(t/datetime-from {:year 2021 :date (t/date-parse "2020-02-02") :time (t/time-now)})

; to get parts of an entity, start with the subject and add ->
;(t/date->yearmonth (t/date-now))
(t/date->month (t/date-now))
(t/zdt->nano (t/zdt-now))
;(-> (t/instant-now) (t/instant->epochmillis))


;(t/period->days (t/period-parse "P3Y5M3D")) ; > 3

;(t/duration->as-minutes (t/duration-parse "PT3H")) ; > 180

; following won't exist bc years and months are variable length
;(t/period->as-days (t/period-parse "P3Y5M3D"))


;(t/+ (t/duration-parse "PT3H") (t/duration-parse "PT3S"))


;; move date forward 3 days
;(t/>> (t/date-now) (t/period-parse "P3D"))

;(-> (t/date-now) (t/with {:year 2021 :month 7}))
;(-> (t/date-now) (t/with-year 3030))

; todo - is this easily doable with platform api??
;(-> (t/date-now) (t/truncate-to-month))
;(-> (t/instant-now) (t/truncate-to-month))


;only entities of the same type can be compared

(t/>= (t/date-parse "2020-05-05") (t/date-parse "2021-05-05"))


(t/max (t/date-parse "2020-05-05") (t/date-parse "2021-05-05") (t/date-parse "1920-05-05"))

; you must specify unit
;(t/until a b :minutes)




)
Loading

0 comments on commit b925cf1

Please sign in to comment.