1//! # Description
2//!
3//! Complete drop-in replacement for [`std::time`] that works in browsers.
4//!
5//! Currently [`Instant::now()`] and [`SystemTime::now()`] will simply panic
6//! when using the `wasm32-unknown-unknown` target. This implementation uses
7//! [`Performance.now()`] for [`Instant`] and [`Date.now()`] for [`SystemTime`]
8//! to offer a drop-in replacement that works in browsers.
9//!
10//! At the same time the library will simply re-export [`std::time`] when not
11//! using the `wasm32-unknown-unknown` target and will not pull in any
12//! dependencies.
13//!
14//! Additionally, if compiled with `target-feature = "atomics"` it will
15//! synchronize the timestamps to account for different context's, like web
16//! workers. See [`Performance.timeOrigin`] for more information.
17//!
18//! Using `-Ctarget-feature=+nontrapping-fptoint` will improve the performance
19//! of [`Instant::now()`] and [`SystemTime::now()`], but the vast majority of
20//! the time is still spent going through JS.
21//!
22//! # Target
23//!
24//! This library specifically targets browsers, that support
25//! [`Performance.now()`], with the `wasm32-unknown-unknown` target. Emscripten
26//! is not supported. WASI doesn't require support as it has it's own native API
27//! to deal with [`std::time`].
28//!
29//! Furthermore it depends on [`wasm-bindgen`], which is required. This library
30//! will continue to depend on it until a viable alternative presents itself, in
31//! which case multiple ecosystems could be supported.
32//!
33//! # Note
34//!
35//! ## Ticking during sleep
36//!
37//! Currently a known bug is affecting browsers on operating system other then
38//! Windows. This bug prevents [`Instant`] from continuing to tick when the
39//! context is asleep. This doesn't necessarily conflict with Rusts requirements
40//! of [`Instant`], but might still be unexpected.
41//!
42//! See [the MDN documentation on this](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now#ticking_during_sleep) for more information.
43//!
44//! ## Context support
45//!
46//! The implementation of [`Instant::now()`] relies on the availability of the
47//! [`Performance` object], a lack thereof will cause a panic. This can happen
48//! if called from a [worklet].
49//!
50//! # Usage
51//!
52//! You can simply import the types you need:
53//! ```rust
54//! use web_time::{Instant, SystemTime};
55//!
56//! let now = Instant::now();
57//! let time = SystemTime::now();
58//! ```
59//!
60//! # Features
61//!
62//! ## `serde`
63//!
64//! Implements [`serde::Deserialize`] and [`serde::Serialize`] for
65//! [`SystemTime`].
66//!
67//! # MSRV
68//!
69//! As this library heavily relies on [`wasm-bindgen`] the MSRV depends on it.
70//! At the point of time this was written the MSRV is 1.60.
71//!
72//! # Alternatives
73//!
74//! [instant](https://crates.io/crates/instant) [![Crates.io](https://img.shields.io/crates/v/instant.svg)](https://crates.io/crates/instant) is a popular alternative! However the API it implements doesn't match [`std::time`] exactly.
75//!
76//! # Contributing
77//!
78//! See the [CONTRIBUTING] file for details.
79//!
80//! # Attribution
81//!
82//! Inspiration was taken from the [instant](https://github.com/sebcrozet/instant/tree/v0.1.12) project.
83//!
84//! Additional insight was taken from the [time](https://github.com/time-rs/time/tree/v0.3.20) project.
85//!
86//! # Changelog
87//!
88//! See the [CHANGELOG] file for details.
89//!
90//! # License
91//!
92//! Licensed under either of
93//!
94//! - Apache License, Version 2.0 ([LICENSE-APACHE] or <http://www.apache.org/licenses/LICENSE-2.0>)
95//! - MIT license ([LICENSE-MIT] or <http://opensource.org/licenses/MIT>)
96//!
97//! at your option.
98//!
99//! ## Copyright
100//!
101//! A majority of the code and documentation was taken from [`std::time`]. For
102//! license information see [#License](https://github.com/rust-lang/rust/tree/1.68.1#license).
103//!
104//! ## Contribution
105//!
106//! Unless you explicitly state otherwise, any contribution intentionally
107//! submitted for inclusion in the work by you, as defined in the Apache-2.0
108//! license, shall be dual licensed as above, without any additional terms or
109//! conditions.
110//!
111//! [CHANGELOG]: https://github.com/daxpedda/web-time/blob/v1.1.0/CHANGELOG.md
112//! [CONTRIBUTING]: https://github.com/daxpedda/web-time/blob/v1.1.0/CONTRIBUTING.md
113//! [LICENSE-MIT]: https://github.com/daxpedda/web-time/blob/v1.1.0/LICENSE-MIT
114//! [LICENSE-APACHE]: https://github.com/daxpedda/web-time/blob/v1.1.0/LICENSE-APACHE
115//! [worklet]: https://developer.mozilla.org/en-US/docs/Web/API/Worklet
116//! [`Date.now()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now
117//! [`Instant`]: https://doc.rust-lang.org/std/time/struct.Instant.html
118//! [`Instant::now()`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now
119//! [`SystemTime`]: https://doc.rust-lang.org/std/time/struct.SystemTime.html
120//! [`SystemTime::now()`]: https://doc.rust-lang.org/std/time/struct.SystemTime.html#method.now
121//! [`std::time`]: https://doc.rust-lang.org/stable/std/time/
122//! [`performance.now()`]: https://developer.mozilla.org/en-US/docs/Web/API/Performance/now
123//! [`Performance.timeOrigin`]: https://developer.mozilla.org/en-US/docs/Web/API/Performance/timeOrigin
124//! [`Performance` object]: https://developer.mozilla.org/en-US/docs/Web/API/performance_property
125#![cfg_attr(
126 any(not(feature = "serde"), not(target_family = "wasm")),
127 doc = "[`serde::Deserialize`]: https://docs.rs/serde/1/serde/trait.Deserialize.html",
128 doc = "[`serde::Serialize`]: https://docs.rs/serde/1/serde/trait.Serialize.html"
129)]
130//! [`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen
131
132#![cfg_attr(docsrs, feature(doc_cfg))]
133
134#[cfg(all(target_family = "wasm", target_os = "unknown"))]
135mod time;
136#[cfg(any(all(target_family = "wasm", target_os = "unknown"), docsrs))]
137#[cfg_attr(docsrs, doc(cfg(Web)))]
138pub mod web;
139
140#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
141pub use std::time::*;
142
143#[cfg(all(target_family = "wasm", target_os = "unknown"))]
144pub use self::time::*;
145