Initial commit

Author: rpunkfu

.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  fmt:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --all -- --check
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - run: cargo clippy --all-targets --all-features -- -D warnings
+
+  test:
+    name: Test (${{ matrix.features }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        features:
+          - ""
+          - "--no-default-features"
+          - "--all-features"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo test ${{ matrix.features }}
+
+  doc:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo doc --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: -D warnings
+
+  no-std:
+    name: no_std Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo check --no-default-features

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.lock

@@ -0,0 +1,33 @@
+[package]
+name = "value-extra"
+version = "0.1.0"
+edition = "2024"
+description = "A tri-state Patch<T> type for partial update semantics — distinguishing between 'has value', 'absent', and 'explicitly null'"
+license = "MIT"
+repository = "https://github.com/itsfoxstudio/value-extra"
+documentation = "https://docs.rs/value-extra"
+keywords = ["patch", "option", "update", "serde", "api"]
+categories = ["data-structures", "rust-patterns"]
+authors = ["Fox Studio (Oskar Cieslik)"]
+readme = "README.md"
+
+[features]
+default = ["std"]
+std = []
+serde = ["dep:serde"]
+
+[dependencies]
+serde = { version = "1", default-features = false, optional = true }
+
+[dev-dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+[profile.release]
+lto = true
+codegen-units = 1
+opt-level = 3
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

Cargo.toml

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fox Studio (Oskar Cieslik)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -0,0 +1,111 @@
+# value-extra
+
+[![Crates.io](https://img.shields.io/crates/v/value-extra.svg)](https://crates.io/crates/value-extra)
+[![Documentation](https://docs.rs/value-extra/badge.svg)](https://docs.rs/value-extra)
+[![License](https://img.shields.io/crates/l/value-extra.svg)](LICENSE)
+[![CI](https://github.com/itsfoxstudio/value-extra/actions/workflows/ci.yml/badge.svg)](https://github.com/itsfoxstudio/value-extra/actions/workflows/ci.yml)
+
+A tri-state `Patch<T>` type for partial update semantics — distinguishing between "has value", "absent", and "explicitly null".
+
+## Installation
+
+```toml
+[dependencies]
+value-extra = "0.1"
+
+# With serde support
+value-extra = { version = "0.1", features = ["serde"] }
+```
+
+## Quick Start
+
+```rust
+use value_extra::Patch;
+
+fn apply_name_patch(current: &mut Option<String>, patch: Patch<String>) {
+    match patch {
+        Patch::Some(new) => *current = Some(new),
+        Patch::None => *current = None,  // explicitly clear
+        Patch::Empty => {}               // no change
+    }
+}
+```
+
+## The Problem
+
+When handling partial updates (PATCH requests, config merging, etc.), `Option<T>` conflates two distinct states:
+
+- **Field is absent** → don't touch the existing value
+- **Field is explicitly null** → clear/reset the value
+
+This leads to bugs where missing fields accidentally clear data.
+
+## The Solution
+
+`Patch<T>` provides three states:
+
+| JSON Input | Patch State | Meaning |
+|------------|-------------|---------|
+| `{ "name": "Alice" }` | `Patch::Some("Alice")` | Set to value |
+| `{ "name": null }` | `Patch::None` | Explicitly clear |
+| `{ }` | `Patch::Empty` | Leave unchanged |
+
+## Serde Usage
+
+```rust
+use value_extra::Patch;
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize)]
+struct UserPatch {
+    #[serde(default, skip_serializing_if = "Patch::is_empty")]
+    name: Patch<String>,
+    #[serde(default, skip_serializing_if = "Patch::is_empty")]
+    email: Patch<String>,
+}
+
+fn apply_user_patch(user: &mut User, patch: UserPatch) {
+    if let Patch::Some(name) = patch.name {
+        user.name = name;
+    } else if patch.name.is_none() {
+        user.name = String::new();
+    }
+    // ... same for email
+}
+```
+
+## Option-like API
+
+`Patch<T>` mirrors `Option<T>`'s API where it makes sense:
+
+```rust
+use value_extra::Patch;
+
+let patch = Patch::Some(42);
+
+// Queries
+assert!(patch.is_some());
+assert!(!patch.is_empty());
+assert!(!patch.is_none());
+
+// Transformations
+let doubled = patch.map(|x| x * 2);
+assert_eq!(doubled, Patch::Some(84));
+
+// Fallbacks
+let value = Patch::<i32>::Empty.unwrap_or(10);
+assert_eq!(value, 10);
+```
+
+## no_std Support
+
+This crate is `no_std` compatible. Disable default features:
+
+```toml
+[dependencies]
+value-extra = { version = "0.1", default-features = false }
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.