feat: add time_stores feature flag and re-export web_time as cached::time (#259)

- Add a new 'time_stores' feature flag to gate all time-dependent cache
  types so the crate can compile for targets without system time
  (e.g. wasm32-unknown-unknown without WASI)
- Expose web_time as a public cached::time module re-export in src/lib.rs
  so users can access time primitives via cached::time without a direct
  web_time dependency
- Keep the old #[doc(hidden)] pub use web_time re-export for backward compat
- Replace all internal web_time:: imports with crate::time:: throughout
- Update doc-comment examples and example files to use cached::time
- Restructure tests/cached.rs with feature-gated modules
- Enable 'time_stores' in the default feature set (no user-visible breakage)
- Bump version: cached 0.59.0, cached_proc_macro 0.27.0
- Regenerate README.md; run cargo fmt

Co-authored-by: James Kominick <james@kominick.com>

Author: Copilot

CHANGELOG.md

@@ -5,6 +5,12 @@
 ## Changed
 ## Removed
 
+## [0.59.0 / [cached_proc_macro[0.27.0]]]
+## Added
+## Changed
+- Fix `examples/wasm` build: add `time_stores` feature to the `cached` dependency (required when using `default-features = false` with `TimedCache`)
+## Removed
+
 ## [0.58.0]
 ## Added
 - Add `redis_async_cache` feature for Redis client-side caching support via the RESP3 protocol

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cached"
-version = "0.58.0"
+version = "0.59.0"
 authors = ["James Kominick <james@kominick.com>"]
 description = "Generic cache implementations and simplified function memoization"
 repository = "https://github.com/jaemk/cached"
@@ -16,7 +16,7 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
-default = ["proc_macro", "ahash"]
+default = ["proc_macro", "ahash", "time_stores"]
 proc_macro = ["cached_proc_macro", "cached_proc_macro_types"]
 ahash = ["dep:ahash", "hashbrown/default"]
 async = ["futures", "tokio", "async-trait"]
@@ -39,9 +39,10 @@ redis_async_cache = [
 redis_ahash = ["redis_store", "redis/ahash"]
 disk_store = ["sled", "serde", "rmp-serde", "directories"]
 wasm = []
+time_stores = []
 
 [dependencies.cached_proc_macro]
-version = "0.26.0"
+version = "0.27.0"
 path = "cached_proc_macro"
 optional = true
 
@@ -152,7 +153,15 @@ required-features = ["async", "proc_macro"]
 
 [[example]]
 name = "expiring_sized_cache"
-required-features = ["async_tokio_rt_multi_thread"]
+required-features = ["async_tokio_rt_multi_thread", "time_stores"]
+
+[[example]]
+name = "basic_proc_macro"
+required-features = ["time_stores", "proc_macro"]
+
+[[example]]
+name = "kitchen_sink_proc_macro"
+required-features = ["time_stores", "proc_macro"]
 
 [[example]]
 name = "disk"

README.md

@@ -22,7 +22,7 @@ of un-cached arguments, specify `#[cached(sync_writes = "default")]` / `#[once(s
 
 **Features**
 
-- `default`: Include `proc_macro` and `ahash` features
+- `default`: Include `proc_macro`, `ahash`, and `time_stores` features
 - `proc_macro`: Include proc macros
 - `ahash`: Enable the optional `ahash` hasher as default hashing algorithm.
 - `async`: Include support for async functions and async cache stores
@@ -36,6 +36,8 @@ of un-cached arguments, specify `#[cached(sync_writes = "default")]` / `#[once(s
 - `disk_store`: Include disk cache store
 - `wasm`: Enable WASM support. Note that this feature is incompatible with `tokio`'s multi-thread
    runtime (`async_tokio_rt_multi_thread`) and all Redis features (`redis_store`, `redis_smol`, `redis_tokio`, `redis_ahash`)
+- `time_stores`: Include time-based cache stores ([`TimedCache`], [`TimedSizedCache`], and [`stores::ExpiringSizedCache`]).
+   Disable this feature when targeting environments without system time support (e.g. `wasm32-unknown-unknown` without WASI or JS).
 
 The procedural macros (`#[cached]`, `#[once]`, `#[io_cached]`) offer more features, including async support.
 See the [`proc_macro`](crate::proc_macro) and [`macros`](crate::macros) modules for more samples, and the
@@ -65,7 +67,7 @@ fn fib(n: u64) -> u64 {
 
 ```rust
 use std::thread::sleep;
-use std::time::Duration;
+use cached::time::Duration;
 use cached::proc_macro::cached;
 use cached::SizedCache;
 
@@ -124,7 +126,7 @@ fn doesnt_compile() -> Result<String, ()> {
 ```rust,no_run,ignore
 use cached::proc_macro::io_cached;
 use cached::AsyncRedisCache;
-use std::time::Duration;
+use cached::time::Duration;
 use thiserror::Error;
 
 #[derive(Error, Debug, PartialEq, Clone)]
@@ -150,7 +152,7 @@ enum ExampleError {
     } "##
 )]
 async fn async_cached_sleep_secs(secs: u64) -> Result<String, ExampleError> {
-    std::thread::sleep(std::time::Duration::from_secs(secs));
+    std::thread::sleep(cached::time::Duration::from_secs(secs));
     Ok(secs.to_string())
 }
 ```
@@ -179,7 +181,7 @@ enum ExampleError {
     disk = true
 )]
 fn cached_sleep_secs(secs: u64) -> Result<String, ExampleError> {
-    std::thread::sleep(std::time::Duration::from_secs(secs));
+    std::thread::sleep(cached::time::Duration::from_secs(secs));
     Ok(secs.to_string())
 }
 ```

cached_proc_macro/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cached_proc_macro"
-version = "0.26.0"
+version = "0.27.0"
 authors = ["csos95 <csoscss@gmail.com>", "James Kominick <james@kominick.com>"]
 description = "Generic cache implementations and simplified function memoization"
 repository = "https://github.com/jaemk/cached"

cached_proc_macro/src/cached.rs

@@ -125,12 +125,12 @@ pub fn cached(args: TokenStream, input: TokenStream) -> TokenStream {
         }
         (false, None, Some(time), None, None, time_refresh) => {
             let cache_ty = quote! {cached::TimedCache<#cache_key_ty, #cache_value_ty>};
-            let cache_create = quote! {cached::TimedCache::with_lifespan_and_refresh(std::time::Duration::from_secs(#time), #time_refresh)};
+            let cache_create = quote! {cached::TimedCache::with_lifespan_and_refresh(::cached::time::Duration::from_secs(#time), #time_refresh)};
             (cache_ty, cache_create)
         }
         (false, Some(size), Some(time), None, None, time_refresh) => {
             let cache_ty = quote! {cached::TimedSizedCache<#cache_key_ty, #cache_value_ty>};
-            let cache_create = quote! {cached::TimedSizedCache::with_size_and_lifespan_and_refresh(#size, std::time::Duration::from_secs(#time), #time_refresh)};
+            let cache_create = quote! {cached::TimedSizedCache::with_size_and_lifespan_and_refresh(#size, ::cached::time::Duration::from_secs(#time), #time_refresh)};
             (cache_ty, cache_create)
         }
         (false, None, None, None, None, _) => {

cached_proc_macro/src/helpers.rs

@@ -201,7 +201,7 @@ pub(super) fn gen_return_cache_block(
     if let Some(time) = &time {
         quote! {
             let (created_sec, result) = result;
-            if now.duration_since(*created_sec) < std::time::Duration::from_secs(#time) {
+            if now.duration_since(*created_sec) < ::cached::time::Duration::from_secs(#time) {
                 #return_cache_block
             }
         }

cached_proc_macro/src/io_cached.rs

@@ -225,19 +225,19 @@ pub fn io_cached(args: TokenStream, input: TokenStream) -> TokenStream {
                         match time_refresh {
                             Some(time_refresh) => {
                                 if asyncness.is_some() {
-                                    quote! { cached::AsyncRedisCache::new(#cache_prefix, std::time::Duration::from_secs(#time)).set_refresh(#time_refresh).build().await.expect("error constructing AsyncRedisCache in #[io_cached] macro") }
+                                    quote! { cached::AsyncRedisCache::new(#cache_prefix, ::cached::time::Duration::from_secs(#time)).set_refresh(#time_refresh).build().await.expect("error constructing AsyncRedisCache in #[io_cached] macro") }
                                 } else {
                                     quote! {
-                                        cached::RedisCache::new(#cache_prefix, std::time::Duration::from_secs(#time)).set_refresh(#time_refresh).build().expect("error constructing RedisCache in #[io_cached] macro")
+                                        cached::RedisCache::new(#cache_prefix, ::cached::time::Duration::from_secs(#time)).set_refresh(#time_refresh).build().expect("error constructing RedisCache in #[io_cached] macro")
                                     }
                                 }
                             }
                             None => {
                                 if asyncness.is_some() {
-                                    quote! { cached::AsyncRedisCache::new(#cache_prefix, std::time::Duration::from_secs(#time)).build().await.expect("error constructing AsyncRedisCache in #[io_cached] macro") }
+                                    quote! { cached::AsyncRedisCache::new(#cache_prefix, ::cached::time::Duration::from_secs(#time)).build().await.expect("error constructing AsyncRedisCache in #[io_cached] macro") }
                                 } else {
                                     quote! {
-                                        cached::RedisCache::new(#cache_prefix, std::time::Duration::from_secs(#time)).build().expect("error constructing RedisCache in #[io_cached] macro")
+                                        cached::RedisCache::new(#cache_prefix, ::cached::time::Duration::from_secs(#time)).build().expect("error constructing RedisCache in #[io_cached] macro")
                                     }
                                 }
                             }
@@ -297,7 +297,7 @@ pub fn io_cached(args: TokenStream, input: TokenStream) -> TokenStream {
                         None => create,
                         Some(time) => {
                             quote! {
-                                (#create).set_lifespan(std::time::Duration::from_secs(#time))
+                                (#create).set_lifespan(::cached::time::Duration::from_secs(#time))
                             }
                         }
                     };

cached_proc_macro/src/once.rs

@@ -80,7 +80,7 @@ pub fn once(args: TokenStream, input: TokenStream) -> TokenStream {
     let (cache_ty, cache_create) = match &args.time {
         None => (quote! { Option<#cache_value_ty> }, quote! { None }),
         Some(_) => (
-            quote! { Option<(::cached::web_time::Instant, #cache_value_ty)> },
+            quote! { Option<(::cached::time::Instant, #cache_value_ty)> },
             quote! { None },
         ),
     };
@@ -255,21 +255,27 @@ pub fn once(args: TokenStream, input: TokenStream) -> TokenStream {
     fill_in_attributes(&mut attributes, cache_fn_doc_extra);
 
     // put it all together
+    let now_block = if args.time.is_some() {
+        quote! { let now = ::cached::time::Instant::now(); }
+    } else {
+        quote! {}
+    };
+
     let expanded = quote! {
         // Cached static
         #[doc = #cache_ident_doc]
         #ty
         // Cached function
         #(#attributes)*
         #visibility #signature_no_muts {
-            let now = ::cached::web_time::Instant::now();
+            #now_block
             #do_set_return_block
         }
         // Prime cached function
         #[doc = #prime_fn_indent_doc]
         #[allow(dead_code)]
         #visibility #prime_sig {
-            let now = ::cached::web_time::Instant::now();
+            #now_block
             #prime_do_set_return_block
         }
     };

examples/async_std.rs

@@ -1,7 +1,7 @@
 use async_std::task::sleep;
 use cached::proc_macro::cached;
 use cached::proc_macro::once;
-use std::time::Duration;
+use cached::time::Duration;
 
 async fn sleep_secs(secs: u64) {
     sleep(Duration::from_secs(secs)).await;

examples/basic.rs

@@ -1,8 +1,8 @@
 #[macro_use]
 extern crate cached;
 
+use cached::time::{Duration, Instant};
 use std::thread::sleep;
-use std::time::{Duration, Instant};
 
 use cached::SizedCache;