Introduce Str and NonEmptyStr string types with strict validations

- Added `Str` and `NonEmptyStr` classes to represent string values with optional non-empty constraints.
- Implemented `StrType` as an abstract base for string types, alongside its interface (`StrTypeInterface`).
- Enhanced `Assert` class with `nonEmptyString` method for ensuring non-empty string inputs.
- Included extensive unit tests for `Str`, `NonEmptyStr`, and `Assert::nonEmptyString` to validate behavior and edge cases.
- Updated example usages and test utilities to incorporate new string types.

Author: georgedeploy

src/Code/Assert/Assert.php

@@ -63,4 +63,16 @@ public static function integerish(mixed $value, string $message = ''): void
             throw new TypeException($message !== '' ? $message : 'Expected an "integerish" value');
         }
     }
+
+    /**
+     * Assert that the given string is non-empty.
+     *
+     * @throws TypeException
+     */
+    public static function nonEmptyString(string $value, string $message = ''): void
+    {
+        if ($value === '') {
+            throw new TypeException($message !== '' ? $message : 'Value must be a non-empty string');
+        }
+    }
 }

src/Code/String/StrType.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Code\String;
+
+/**
+ * @psalm-immutable
+ */
+abstract readonly class StrType implements StrTypeInterface
+{
+    public function toString(): string
+    {
+        return $this->value();
+    }
+}

src/Code/String/StrTypeInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Code\String;
+
+/**
+ * @psalm-immutable
+ */
+interface StrTypeInterface
+{
+    public function value(): string;
+
+    public static function fromString(string $value): self;
+
+    public function toString(): string;
+}

src/String/NonEmptyStr.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String;
+
+use PhpTypedValues\Code\Assert\Assert;
+use PhpTypedValues\Code\Exception\TypeException;
+use PhpTypedValues\Code\String\StrType;
+
+/**
+ * @psalm-immutable
+ */
+final readonly class NonEmptyStr extends StrType
+{
+    /** @var non-empty-string */
+    protected string $value;
+
+    /**
+     * @throws TypeException
+     */
+    public function __construct(string $value)
+    {
+        Assert::nonEmptyString($value, 'Value must be a non-empty string');
+
+        /** @var non-empty-string $value */
+        $this->value = $value;
+    }
+
+    /**
+     * @throws TypeException
+     */
+    public static function fromString(string $value): self
+    {
+        return new self($value);
+    }
+
+    /** @return non-empty-string */
+    public function value(): string
+    {
+        return $this->value;
+    }
+}

src/String/Str.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String;
+
+use PhpTypedValues\Code\String\StrType;
+
+/**
+ * Represents any PHP string.
+ *
+ * @psalm-immutable
+ */
+final readonly class Str extends StrType
+{
+    protected string $value;
+
+    public function __construct(string $value)
+    {
+        $this->value = $value;
+    }
+
+    public static function fromString(string $value): self
+    {
+        return new self($value);
+    }
+
+    public function value(): string
+    {
+        return $this->value;
+    }
+}

src/psalmTest.php

@@ -12,6 +12,8 @@
 use PhpTypedValues\Integer\NonNegativeInt;
 use PhpTypedValues\Integer\PositiveInt;
 use PhpTypedValues\Integer\WeekDayInt;
+use PhpTypedValues\String\NonEmptyStr;
+use PhpTypedValues\String\Str;
 
 /**
  * Integer.
@@ -23,6 +25,14 @@
 
 echo Integer::fromString('10')->toString();
 
+/**
+ * String.
+ */
+testString(Str::fromString('hi')->value());
+testNonEmptyString(NonEmptyStr::fromString('hi')->value());
+
+echo Str::fromString('hi')->toString();
+
 /**
  * Artificial functions.
  */
@@ -54,3 +64,16 @@ function testWeekDayInt(int $i): int
 {
     return $i;
 }
+
+function testString(string $i): string
+{
+    return $i;
+}
+
+/**
+ * @param non-empty-string $i
+ */
+function testNonEmptyString(string $i): string
+{
+    return $i;
+}

tests/Unit/Code/Assert/AssertTest.php

@@ -53,3 +53,20 @@
     Assert::integerish(5, '');
     expect(true)->toBeTrue();
 });
+
+it('nonEmptyString throws with default message when empty', function (): void {
+    expect(fn() => Assert::nonEmptyString('', ''))
+        ->toThrow(TypeException::class, 'Value must be a non-empty string');
+});
+
+it('nonEmptyString throws with custom message when provided', function (): void {
+    expect(fn() => Assert::nonEmptyString('', 'custom non-empty message'))
+        ->toThrow(TypeException::class, 'custom non-empty message');
+});
+
+it('nonEmptyString does not throw for non-empty strings', function (): void {
+    Assert::nonEmptyString('a', '');
+    Assert::nonEmptyString('  ', '');
+    Assert::nonEmptyString("\u{1F600}", '');
+    expect(true)->toBeTrue();
+});

tests/Unit/Code/String/StrTypeTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\String\Str;
+
+it('fromString returns exact value and toString matches', function (): void {
+    $s1 = Str::fromString('hello');
+    expect($s1->value())->toBe('hello')
+        ->and($s1->toString())->toBe('hello');
+
+    $s2 = Str::fromString('');
+    expect($s2->value())->toBe('')
+        ->and($s2->toString())->toBe('');
+});
+
+it('handles unicode and whitespace transparently', function (): void {
+    $unicode = Str::fromString('Привет 🌟');
+    expect($unicode->value())->toBe('Привет 🌟')
+        ->and($unicode->toString())->toBe('Привет 🌟');
+
+    $ws = Str::fromString('  spaced  ');
+    expect($ws->value())->toBe('  spaced  ')
+        ->and($ws->toString())->toBe('  spaced  ');
+});

tests/Unit/String/NonEmptyStrTypeTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Code\Exception\TypeException;
+use PhpTypedValues\String\NonEmptyStr;
+
+it('constructs and preserves non-empty string', function (): void {
+    $s = new NonEmptyStr('hello');
+    expect($s->value())->toBe('hello')
+        ->and($s->toString())->toBe('hello');
+});
+
+it('allows whitespace and unicode as non-empty', function (): void {
+    $w = new NonEmptyStr(' ');
+    $u = NonEmptyStr::fromString('🙂');
+    expect($w->value())->toBe(' ')
+        ->and($u->toString())->toBe('🙂');
+});
+
+it('throws on empty string via constructor', function (): void {
+    expect(fn() => new NonEmptyStr(''))
+        ->toThrow(TypeException::class, 'Value must be a non-empty string');
+});
+
+it('throws on empty string via fromString', function (): void {
+    expect(fn() => NonEmptyStr::fromString(''))
+        ->toThrow(TypeException::class, 'Value must be a non-empty string');
+});