Add initial time module with Date facade and chrono primitives

Author: GaspardKirira

CMakeLists.txt

@@ -153,9 +153,13 @@ endif()
 option(VIX_TIME_BUILD_TESTS "Build time module tests" OFF)
 
 if (VIX_TIME_BUILD_TESTS)
-  include(CTest)
-  enable_testing()
-  add_subdirectory(tests)
+  if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/tests/CMakeLists.txt")
+    include(CTest)
+    enable_testing()
+    add_subdirectory(tests)
+  else()
+    message(WARNING "[time/tests] VIX_TIME_BUILD_TESTS=ON but tests/CMakeLists.txt not found, skipping.")
+  endif()
 endif()
 
 # ======================================================
@@ -165,9 +169,14 @@ endif()
 option(VIX_TIME_BUILD_EXAMPLES "Build time module examples" OFF)
 
 if (VIX_TIME_BUILD_EXAMPLES)
-  add_subdirectory(examples)
+  if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/examples/CMakeLists.txt")
+    add_subdirectory(examples)
+  else()
+    message(WARNING "[time/examples] VIX_TIME_BUILD_EXAMPLES=ON but examples/CMakeLists.txt not found, skipping.")
+  endif()
 endif()
 
+
 # ======================================================
 # Summary
 # ======================================================

README.md

@@ -1,2 +1,146 @@
-# time
-Provides a simple, explicit API for working with dates, times, timestamps, and durations in C++. Designed for ergonomics similar to Node.js and Python, while remaining predictable, type-safe, and aligned with modern C++ and std::chrono.
+# vix::time
+
+**Time and date utilities for Vix.cpp.**
+
+`vix::time` provides a simple, explicit, and predictable API for working with
+dates, times, timestamps, and durations in modern C++.
+
+The design is inspired by the ergonomics of Node.js and Python, while remaining
+fully type-safe, chrono-based, and explicit.
+
+---
+
+## Features
+
+- 📅 **Date facade** (`Date::now()`, `Date::parse()`)
+- 🕒 **DateTime** with UTC support and ISO-8601 parsing
+- ⏱ **Timestamp** (epoch-based, nanosecond precision)
+- ⌛ **Duration** (strongly typed, chrono-backed)
+- 🧭 **System & Steady clocks**
+- 📦 Header-only (v1)
+- 🚫 No hidden allocations, no magic, no dependencies
+
+---
+
+## Installation
+
+`vix::time` is designed to be used as part of the Vix umbrella project.
+
+```cmake
+add_subdirectory(modules/time)
+```
+
+Or link against the exported target:
+
+```cmake
+target_link_libraries(your_target PRIVATE vix::time)
+```
+
+---
+
+## Quick Example
+
+```cpp
+#include <vix/time/time.hpp>
+#include <iostream>
+
+using namespace vix::time;
+
+int main()
+{
+  Date today = Date::now();
+  std::cout << today.to_string() << "\n";
+
+  DateTime now = DateTime::now_utc();
+  std::cout << now.to_string_utc() << "\n";
+
+  Timestamp t0 = Timestamp::now();
+  Timestamp t1 = t0 + Duration::seconds(1);
+
+  Duration delta = t1 - t0;
+  std::cout << delta.count_seconds() << "s\n";
+}
+```
+
+---
+
+## API Overview
+
+### Date
+
+```cpp
+Date::now();
+Date::today();
+Date::parse("YYYY-MM-DD");
+```
+
+Represents a calendar date without time.
+
+### DateTime
+
+```cpp
+DateTime::now_utc();
+DateTime::parse("YYYY-MM-DDTHH:MM:SSZ");
+```
+
+Represents a full date + time in UTC.
+
+### Timestamp
+
+```cpp
+Timestamp::now();
+Timestamp::from_seconds(1700000000);
+```
+
+Absolute point in time (nanoseconds since Unix epoch).
+
+### Duration
+
+```cpp
+Duration::seconds(5);
+Duration::milliseconds(250);
+```
+
+Strongly typed time spans.
+
+### Clocks
+
+```cpp
+SystemClock::now();          // wall time (Timestamp)
+SteadyClock::now_chrono();   // monotonic clock
+SteadyClock::since(start);   // elapsed Duration
+```
+
+---
+
+## Design Principles
+
+- Explicit over implicit
+- Strong types instead of raw integers
+- Predictable behavior
+- Minimal surface API
+- No hidden global state
+
+`vix::time` is intended to be a foundational module used by:
+
+- sync
+- cache
+- WAL
+- retry / timeout logic
+- scheduling
+
+---
+
+## Status
+
+- **Version**: v0.1.0
+- **Mode**: Header-only
+- **C++ Standard**: C++20
+- **Stability**: Experimental (API subject to refinement)
+
+---
+
+## License
+
+MIT License
+Copyright © 2026 Gaspard Kirira

examples/CMakeLists.txt

@@ -0,0 +1,56 @@
+#  @file CMakeLists.txt
+#  @author Gaspard Kirira
+#
+#  Copyright 2026, Gaspard Kirira.
+#  All rights reserved.
+#  https://github.com/vixcpp/time
+#
+#  Use of this source code is governed by a MIT license
+#  that can be found in the LICENSE file.
+#
+# ====================================================================
+# Vix.cpp - vix::time examples
+# ====================================================================
+
+cmake_minimum_required(VERSION 3.20)
+
+# Collect example sources (each .cpp becomes one executable)
+file(GLOB EXAMPLE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/*.cpp")
+
+if (NOT EXAMPLE_SOURCES)
+  message(STATUS "[time/examples] No .cpp examples found.")
+  return()
+endif()
+
+message(STATUS "[time/examples] Found ${EXAMPLE_SOURCES}")
+
+foreach (src ${EXAMPLE_SOURCES})
+  get_filename_component(name ${src} NAME_WE)
+
+  # Prefix to avoid collisions in umbrella builds
+  set(target "vix_time_example_${name}")
+
+  add_executable(${target} ${src})
+
+  target_compile_features(${target} PRIVATE cxx_std_20)
+
+  # Link the module
+  target_link_libraries(${target} PRIVATE vix::time)
+
+  # Optional umbrella helpers (if present)
+  if (TARGET vix_warnings)
+    target_link_libraries(${target} PRIVATE vix_warnings)
+  endif()
+
+  if (VIX_ENABLE_SANITIZERS AND TARGET vix_sanitizers)
+    target_link_libraries(${target} PRIVATE vix_sanitizers)
+  endif()
+
+  # Nice output folder in IDEs
+  set_target_properties(${target} PROPERTIES
+    FOLDER "examples/time"
+    OUTPUT_NAME ${name}
+  )
+
+  message(STATUS "[time/examples] Added ${target} -> ${name}")
+endforeach()

examples/basic_date.cpp

@@ -0,0 +1,69 @@
+/**
+ * @file basic_date.cpp
+ *
+ * Minimal example demonstrating the Vix time module.
+ */
+
+#include <iostream>
+
+#include <vix/time/time.hpp>
+
+using namespace vix::time;
+
+int main()
+{
+  // --------------------------------------------
+  // Date facade (Node.js / Python-like)
+  // --------------------------------------------
+
+  Date today = Date::now();
+  std::cout << "Today (UTC): " << today.to_string() << "\n";
+
+  Date parsed = Date::parse("2026-02-07");
+  std::cout << "Parsed date: " << parsed.to_string() << "\n";
+
+  // Convert date to timestamp (00:00:00 UTC)
+  Timestamp day_start = parsed.to_timestamp_utc();
+  std::cout << "Day start (epoch seconds): "
+            << day_start.seconds_since_epoch() << "\n";
+
+  // --------------------------------------------
+  // DateTime
+  // --------------------------------------------
+
+  DateTime now = DateTime::now_utc();
+  std::cout << "Now (UTC): " << now.to_string_utc() << "\n";
+
+  DateTime parsed_dt = DateTime::parse("2026-02-07T10:30:15Z");
+  std::cout << "Parsed datetime: "
+            << parsed_dt.to_string_utc() << "\n";
+
+  // --------------------------------------------
+  // Timestamp + Duration arithmetic
+  // --------------------------------------------
+
+  Timestamp t0 = Timestamp::now();
+  Duration wait = Duration::seconds(2);
+
+  Timestamp t1 = t0 + wait;
+  Duration delta = t1 - t0;
+
+  std::cout << "Delta (seconds): "
+            << delta.count_seconds() << "\n";
+
+  // --------------------------------------------
+  // Steady clock (elapsed time)
+  // --------------------------------------------
+
+  auto start = SteadyClock::now_chrono();
+  // simulate work
+  int sink = 0;
+  for (int i = 0; i < 1'000'000; ++i)
+    sink += i;
+  Duration elapsed = SteadyClock::since(start);
+
+  std::cout << "Elapsed (ms): "
+            << elapsed.count_ms() << "\n";
+
+  return 0;
+}

include/vix/time/Clock.hpp

@@ -0,0 +1,72 @@
+/**
+ * @file Clock.hpp
+ * @author Gaspard Kirira
+ *
+ * Copyright 2026, Gaspard Kirira.
+ * All rights reserved.
+ * https://github.com/vixcpp/time
+ *
+ * Use of this source code is governed by a MIT license
+ * that can be found in the LICENSE file.
+ *
+ * =====================================================
+ * Vix.cpp — Time Module / Clock
+ * =====================================================
+ *
+ * Clock utilities for retrieving current time.
+ *
+ * - System clock: wall time, epoch-based (Timestamp)
+ * - Steady clock: monotonic time for measuring durations
+ *
+ * This module keeps APIs explicit and predictable.
+ */
+
+#ifndef VIX_TIME_CLOCK_HPP
+#define VIX_TIME_CLOCK_HPP
+
+#include <chrono>
+
+#include <vix/time/Duration.hpp>
+#include <vix/time/Timestamp.hpp>
+
+namespace vix::time
+{
+  /**
+   * @brief System clock helpers (wall time).
+   *
+   * Returns epoch-based timestamps (nanoseconds since epoch).
+   */
+  struct SystemClock
+  {
+    static Timestamp now() noexcept
+    {
+      return Timestamp::now();
+    }
+  };
+
+  /**
+   * @brief Steady/monotonic clock helpers.
+   *
+   * Used for measuring elapsed time (timeouts, benchmarks).
+   * Not related to wall time and not convertible to Timestamp.
+   */
+  class SteadyClock
+  {
+  public:
+    using chrono_tp = std::chrono::time_point<std::chrono::steady_clock, std::chrono::nanoseconds>;
+
+    static chrono_tp now_chrono() noexcept
+    {
+      return std::chrono::time_point_cast<std::chrono::nanoseconds>(std::chrono::steady_clock::now());
+    }
+
+    static Duration since(const chrono_tp &start) noexcept
+    {
+      const auto delta = now_chrono() - start;
+      return Duration(std::chrono::duration_cast<std::chrono::nanoseconds>(delta));
+    }
+  };
+
+} // namespace vix::time
+
+#endif // VIX_TIME_CLOCK_HPP