Introduce DateTimeBasic and FloatBasic types; refactor exception handling and enhance typed values library

- Added `DateTimeBasic` type for PHP `DateTimeImmutable` representations with strict validation and ISO-8601 handling.
- Introduced `FloatBasic` type to represent float values with validations.
- Created `DateTimeType` and `FloatType` abstract classes with respective interfaces for consistent base behavior.
- Refactored exception classes, replacing `TypeException` with more specific exceptions (`NumericTypeException`, `StringTypeException`, `DateTimeTypeException`) for granular error handling.
- Updated `Assert` class to include numeric float validation and enhanced `nonEmptyString` verification.
- Migrated integer and string types (`Integer`, `Str`) to new exception classes; adjusted tests accordingly.
- Expanded documentation and examples in `README.md` and `USAGE.md` to include `Float` and `DateTime` types.
- Maintained full test coverage, including mutation testing.

Author: georgedeploy

AIPROMT.md

@@ -0,0 +1,42 @@
+# Main project instructions
+
+## Events
+
+### On new type generation
+
+- add new type to `src/"type name"` folder
+- add new type assertions to `src/Code/Assert/Assert.php` if needed
+- add new type tests to `tests/Unit/"type name"/"TypeName"Test.php`
+- add new Exception class to `src/Exception` folder and use it
+
+## Coding style
+
+- PHP 8.2 used
+- use strict typing
+- follow PSR-12 coding standards
+- use meaningful variable and function names
+- keep code clean and readable
+- PSALM v6 static analysis is used
+
+## Folder structure 
+
+- `src/Code` folder contains the framework internal code
+- other folders like `src/"type"` contains specific types 
+- `src/psalmTest.php` contains types usage to avoid Psalm issues like `unused method`
+- `src/Code/Assert/Assert.php` contains `assert` methods, add new methods instead of checking conditions directly in classes. Prefer to use Assert::"methos()". 
+
+## Tests
+
+- are in `tests` folder
+- used PhpUnit v11 and PEST v3
+- use PEST syntax `it` instead of `test`
+- keep the folder structure as tested src files
+- test coverage should be 100%
+- mutation tests used, avoid fails 
+
+## Documentation
+
+- keep it simple
+- use Markdown format
+- include project overview in README.md, short examples of how to install, use, and extend
+- installation instructions, usage examples, develop instructions in `docs` folder

README.md

@@ -24,35 +24,57 @@ composer require georgii-web/php-typed-values
 Usage
 -----
 
-Create and use typed integers with validation built in.
+Create and use typed values with validation built in.
 
 ```php
-use PhpTypedValues\\Integer\\PositiveInt;
-use PhpTypedValues\\Integer\\NonNegativeInt;
-use PhpTypedValues\\Integer\\WeekDayInt;
-use PhpTypedValues\\Integer\\Integer;
+// Integers
+use PhpTypedValues\Integer\IntegerBasic;
+use PhpTypedValues\Integer\PositiveInt;
+use PhpTypedValues\Integer\NonNegativeInt;
+use PhpTypedValues\Integer\WeekDayInt;
 
-$age = new PositiveInt(27);          // ok (positive-int)
-$retries = new NonNegativeInt(0);    // ok (0 or positive)
-$weekday = new WeekDayInt(5);        // ok (1..7)
-$any = new Integer(-42);             // ok (any integer)
+$age      = new PositiveInt(27);       // ok (positive-int)
+$retries  = new NonNegativeInt(0);     // ok (0 or positive)
+$weekday  = new WeekDayInt(5);         // ok (1..7)
+$anyInt   = new IntegerBasic(-42);     // ok (any integer)
 
-// Construct from string
 $fromString = PositiveInt::fromString('123');
 
-// Access the underlying scalar value
-$ageValue = $age->value(); // 27
-echo $weekday->toString(); // "5"
+// Strings
+use PhpTypedValues\String\StringBasic;
+use PhpTypedValues\String\NonEmptyStr;
+
+$greeting = StringBasic::fromString('hello');
+$name     = new NonEmptyStr('Alice');  // throws if empty
+
+// Floats
+use PhpTypedValues\Float\FloatBasic;
+use PhpTypedValues\Float\NonNegativeFloat;
+
+$price    = FloatBasic::fromString('19.99');
+$ratio    = new NonNegativeFloat(0.5);    // > 0 required
+
+// Access the underlying scalar value / string form
+$ageValue = $age->value();        // 27
+echo $weekday->toString();        // "5"
+echo $price->toString();          // "19.99"
 ```
 
 All value objects are immutable; invalid input throws an exception with a helpful message.
 
-Provided integer types (so far):
-
-- Integer — any PHP integer
-- PositiveInt — positive integer (> 0)
-- NonNegativeInt — zero or positive integer (>= 0)
-- WeekDayInt — integer in range 1..7
+Provided types (so far):
+
+- Integers
+  - IntegerBasic — any PHP integer
+  - PositiveInt — positive integer (> 0)
+  - NonNegativeInt — zero or positive integer (>= 0)
+  - WeekDayInt — integer in range 1..7
+- Strings
+  - StringBasic — any PHP string
+  - NonEmptyStr — non-empty string
+- Floats
+  - FloatBasic — any PHP float
+  - PositiveFloat — positive float (> 0)
 
 Why
 ---

docs/USAGE.md

@@ -1,7 +1,7 @@
 Usage
 =====
 
-This page shows concise, up-to-date examples for the available integer value objects.
+This page shows concise, up-to-date examples for the available Integer, String, and Float value objects.
 
 Namespaces
 ----------
@@ -15,31 +15,59 @@ PhpTypedValues
 Available integer types
 -----------------------
 
-- PhpTypedValues\Integer\Integer — any PHP integer
+- PhpTypedValues\Integer\IntegerBasic — any PHP integer
 - PhpTypedValues\Integer\PositiveInt — positive integer (> 0)
 - PhpTypedValues\Integer\NonNegativeInt — zero or positive integer (>= 0)
 - PhpTypedValues\Integer\WeekDayInt — integer in range 1..7
 
+Available string types
+----------------------
+
+- PhpTypedValues\String\StringBasic — any PHP string
+- PhpTypedValues\String\NonEmptyStr — non-empty string
+
+Available float types
+---------------------
+
+- PhpTypedValues\Float\FloatBasic — any PHP float
+- PhpTypedValues\Float\PositiveFloat — positive float (> 0)
+
 Quick start
 -----------
 
 ```php
-use PhpTypedValues\Integer\Integer;
+// Integers
+use PhpTypedValues\Integer\IntegerBasic;
 use PhpTypedValues\Integer\NonNegativeInt;
 use PhpTypedValues\Integer\PositiveInt;
 use PhpTypedValues\Integer\WeekDayInt;
 
-$any = new Integer(-10);          // ok
+$any = new IntegerBasic(-10);     // ok
 $pos = new PositiveInt(1);        // ok
 $nn  = new NonNegativeInt(0);     // ok
 $wd  = new WeekDayInt(7);         // ok (1..7)
 
 // From string
 $posFromString = PositiveInt::fromString('123');
 
+// Strings
+use PhpTypedValues\String\StringBasic;
+use PhpTypedValues\String\NonEmptyStr;
+
+$greeting = StringBasic::fromString('hello');
+$name     = new NonEmptyStr('Alice'); // throws if empty
+
+// Floats
+use PhpTypedValues\Float\FloatBasic;
+use PhpTypedValues\Float\NonNegativeFloat;
+
+$price = FloatBasic::fromString('19.99');
+$ratio = new NonNegativeFloat(0.5);  // > 0
+
 // Accessing the raw value and string form
 echo $pos->value();     // 1
 echo $wd->toString();   // "7"
+echo $price->toString(); // "19.99"
 ```
 
 Validation errors
@@ -49,13 +77,20 @@ Invalid input throws an exception with a helpful message.
 
 ```php
 use PhpTypedValues\Integer\PositiveInt;
+use PhpTypedValues\String\NonEmptyStr;
+use PhpTypedValues\Float\NonNegativeFloat;
 
-new PositiveInt(0);     // throws: Value must be a positive integer
+new PositiveInt(0);              // throws: Value must be a positive integer
 PositiveInt::fromString('12.3'); // throws: String has no valid integer
+
+new NonEmptyStr('');             // throws: Value must be a non-empty string
+
+new NonNegativeFloat(0.0);          // throws: Value must be a positive float
+NonNegativeFloat::fromString('abc'); // throws: String has no valid float
 ```
 
 Notes
 -----
 
 - All value objects are immutable (readonly) and type-safe.
-- Utility constructors: fromInt(int) and fromString(string) are provided where applicable.
+- Utility constructors: fromInt(int)/fromString(string), fromFloat(float)/fromString(string) are provided where applicable.

src/Code/Assert/Assert.php

@@ -4,75 +4,68 @@
 
 namespace PhpTypedValues\Code\Assert;
 
-use PhpTypedValues\Code\Exception\TypeException;
+use PhpTypedValues\Code\Exception\NumericTypeException;
+use PhpTypedValues\Code\Exception\StringTypeException;
 
 use function is_numeric;
 
 final class Assert
 {
     /**
-     * @throws TypeException
+     * @throws NumericTypeException
      */
     public static function greaterThanEq(int|float $value, int|float $min, string $message = ''): void
     {
         if ($value < $min) {
-            throw new TypeException($message !== '' ? $message : 'Expected a value greater than or equal to the minimum');
+            throw new NumericTypeException($message !== '' ? $message : 'Expected a value greater than or equal to the minimum');
         }
     }
 
     /**
-     * @throws TypeException
+     * @throws NumericTypeException
      */
     public static function lessThanEq(int|float $value, int|float $max, string $message = ''): void
     {
         if ($value > $max) {
-            throw new TypeException($message !== '' ? $message : 'Expected a value less than or equal to the maximum');
+            throw new NumericTypeException($message !== '' ? $message : 'Expected a value less than or equal to the maximum');
         }
     }
 
-    //    /**
-    //     * @throws TypeException
-    //     */
-    //    public static function greaterThan(int|float $value, int|float $min, string $message = ''): void
-    //    {
-    //        if ($value <= $min) {
-    //            throw new TypeException($message !== '' ? $message : 'Expected a value greater than the minimum');
-    //        }
-    //    }
-    //
-    //    /**
-    //     * @throws TypeException
-    //     */
-    //    public static function lessThan(int|float $value, int|float $max, string $message = ''): void
-    //    {
-    //        if ($value >= $max) {
-    //            throw new TypeException($message !== '' ? $message : 'Expected a value less than the maximum');
-    //        }
-    //    }
-
     /**
      * Assert that the given value looks like an integer ("integerish").
      * Accepts numeric strings that represent an integer value (e.g., '5', '5.0'),
      * but rejects non-numeric strings and floats with a fractional part (e.g., '5.5').
      *
-     * @throws TypeException
+     * @throws NumericTypeException
      */
     public static function integerish(mixed $value, string $message = ''): void
     {
         if (!is_numeric($value) || $value != (int) $value) {
-            throw new TypeException($message !== '' ? $message : 'Expected an "integerish" value');
+            throw new NumericTypeException($message !== '' ? $message : 'Expected an "integerish" value');
+        }
+    }
+
+    /**
+     * Assert that the given value is numeric (int/float or numeric string).
+     *
+     * @throws NumericTypeException
+     */
+    public static function numeric(mixed $value, string $message = ''): void
+    {
+        if (!is_numeric($value)) {
+            throw new NumericTypeException($message !== '' ? $message : 'Expected a numeric value');
         }
     }
 
     /**
      * Assert that the given string is non-empty.
      *
-     * @throws TypeException
+     * @throws StringTypeException
      */
     public static function nonEmptyString(string $value, string $message = ''): void
     {
         if ($value === '') {
-            throw new TypeException($message !== '' ? $message : 'Value must be a non-empty string');
+            throw new StringTypeException($message !== '' ? $message : 'Value must be a non-empty string');
         }
     }
 }

src/Code/DateTime/DateTimeType.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Code\DateTime;
+
+use const DATE_ATOM;
+
+use DateTimeImmutable;
+use Exception;
+use PhpTypedValues\Code\Exception\DateTimeTypeException;
+
+/**
+ * @psalm-immutable
+ */
+abstract readonly class DateTimeType implements DateTimeTypeInterface
+{
+    /**
+     * @throws DateTimeTypeException
+     */
+    protected static function parseString(string $value): DateTimeImmutable
+    {
+        // Accept a small, explicit set of formats to avoid accidentally parsing invalid strings as "now".
+        $formats = [
+            DATE_ATOM,            // e.g., 2025-01-02T03:04:05+00:00
+            'Y-m-d\TH:i:s\Z',    // e.g., 2025-01-02T03:04:05Z
+            'Y-m-d H:i:s',        // e.g., 2025-01-02 03:04:05
+            '!Y-m-d',             // e.g., 2025-01-02 (force midnight by resetting unspecified fields)
+        ];
+
+        foreach ($formats as $format) {
+            $dt = DateTimeImmutable::createFromFormat($format, $value);
+            if ($dt instanceof DateTimeImmutable) {
+                $errors = DateTimeImmutable::getLastErrors();
+                $hasIssues = $errors !== false && (($errors['warning_count'] ?? 0) > 0 || ($errors['error_count'] ?? 0) > 0);
+                if (!$hasIssues) {
+                    return $dt;
+                }
+            }
+        }
+
+        // Fallback: try the engine parser for strict ISO-8601 only using DateTimeImmutable constructor
+        try {
+            $fallback = new DateTimeImmutable($value);
+        } catch (Exception) {
+            $fallback = null;
+        }
+
+        if ($fallback instanceof DateTimeImmutable) {
+            // Heuristic: if input clearly looks like an ISO 8601 (contains 'T' and either 'Z' or timezone offset), accept it
+            if (preg_match('/T\d{2}:\d{2}:\d{2}(?:Z|[+\-]\d{2}:?\d{2})$/', $value) === 1) {
+                return $fallback;
+            }
+        }
+
+        throw new DateTimeTypeException('String has no valid datetime');
+    }
+
+    public function toString(): string
+    {
+        // ISO 8601 string representation
+        return $this->value()->format(DATE_ATOM);
+    }
+}