diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..6e47ad1 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,366 @@ +name: CI + +# Pull requests, pushes to main and reuse from release.yml (workflow_call). Single required check +# for branch protection: "CI OK". +on: + pull_request: + push: + branches: [main] + workflow_call: + inputs: + version-suffix: + description: Prerelease label appended to every package version (for example rc.1). Empty packs the versions declared in the csproj files. + type: string + default: '' + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +env: + DOTNET_NOLOGO: true + DOTNET_CLI_TELEMETRY_OPTOUT: true + DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 8.0.x + 9.0.x + + - name: Restore + run: dotnet restore vali-flow.sln + + - name: Build + run: dotnet build vali-flow.sln -c Release --no-restore + + test: + name: test / ${{ matrix.os }} / ${{ matrix.tfm }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest] + tfm: [net8.0, net9.0] + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 8.0.x + 9.0.x + + - name: Environment + shell: bash + run: | + mkdir -p logs + { + echo "### ${{ matrix.os }} / ${{ matrix.tfm }}" + uname -a || true + dotnet --info + } 2>&1 | tee logs/00-environment.log + + - name: Restore + shell: bash + run: | + set -o pipefail + dotnet restore vali-flow.sln 2>&1 | tee logs/01-restore.log + + - name: Build + shell: bash + run: | + set -o pipefail + dotnet build vali-flow.sln -c Release --no-restore -v:minimal -bl:logs/build.binlog 2>&1 | tee logs/02-build.log + + # The 11 test projects, one per package family (Vali-Flow.NoSql.Tests also covers the + # MongoDB translator — there is no separate Vali-Flow.NoSql.MongoDB.Tests project). + - name: Unit tests with coverage on ${{ matrix.tfm }} + shell: bash + run: | + set -o pipefail + status=0 + projects="Vali-Flow.Abstractions.Tests Vali-Flow.Tests Vali-Flow.InMemory.Tests Vali-Flow.Sql.Tests Vali-Flow.NoSql.Tests Vali-Flow.NoSql.Elasticsearch.Tests Vali-Flow.NoSql.Redis.Tests Vali-Flow.NoSql.DynamoDB.Tests Vali-Flow.NoSql.Couchbase.Tests Vali-Flow.NoSql.CosmosDb.Tests Vali-Flow.NoSql.Firestore.Tests" + for project in $projects; do + echo "::group::$project on ${{ matrix.tfm }}" + dotnet test "$project" -c Release --no-build -f "${{ matrix.tfm }}" \ + --logger "console;verbosity=detailed" \ + --logger "trx;LogFileName=$project-${{ matrix.tfm }}.trx" \ + --collect:"XPlat Code Coverage" --results-directory "TestResults/${{ matrix.tfm }}/$project" \ + 2>&1 | tee "logs/03-test-$project.log" || status=1 + echo "::endgroup::" + done + exit $status + + - name: Test totals + if: always() + shell: bash + run: | + python3 - <<'PY' + import glob + import os + import xml.etree.ElementTree as ET + + rows = ["| Project | Total | Passed | Failed | Skipped |", "|---|---:|---:|---:|---:|"] + for path in sorted(glob.glob("TestResults/**/*.trx", recursive=True)): + counters = ET.parse(path).getroot().find(".//{*}Counters") + if counters is None: + continue + name = os.path.basename(path)[:-4] + failed = int(counters.get("failed", 0)) + skipped = int(counters.get("total", 0)) - int(counters.get("executed", 0)) + rows.append(f"| {name} | {counters.get('total')} | {counters.get('passed')} | {failed}{' (!)' if failed else ''} | {skipped} |") + report = "### Tests ${{ matrix.os }} / ${{ matrix.tfm }}\n\n" + "\n".join(rows) + "\n" + print(report) + with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as handle: + handle.write(report + "\n") + PY + + - name: Upload coverage reports + if: always() + uses: actions/upload-artifact@v4 + with: + name: coverage-${{ matrix.os }}-${{ matrix.tfm }} + path: TestResults/**/coverage.cobertura.xml + if-no-files-found: error + retention-days: 7 + + - name: Upload full trace + if: always() + uses: actions/upload-artifact@v4 + with: + name: trace-${{ matrix.os }}-${{ matrix.tfm }} + path: | + logs/** + TestResults/**/*.trx + if-no-files-found: warn + retention-days: 14 + + trace: + name: Full trace (single file) + needs: test + if: always() + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + with: + pattern: trace-* + path: trace + + - name: Merge every log into one file + shell: bash + run: | + out=full-trace.txt + : > "$out" + while IFS= read -r f; do + rel="${f#trace/}" + { + echo + echo "==================================================================" + echo "== ${rel%%/*} :: ${rel#*/}" + echo "==================================================================" + cat "$f" + } >> "$out" + done < <(find trace -name '*.log' | sort) + wc -l "$out" + { + echo "### Full trace" + echo + echo "Download the **full-trace** artifact of this run: one text file with the environment, restore, build and" + echo "detailed test output of every OS x target framework cell." + } >> "$GITHUB_STEP_SUMMARY" + + - name: Upload the single-file trace + uses: actions/upload-artifact@v4 + with: + name: full-trace + path: full-trace.txt + if-no-files-found: error + retention-days: 14 + + coverage: + # NOTE: 95% is a starting gate, not an audited baseline for the 10 packages not measured in the + # session that stood this pipeline up (Vali-Flow itself was: 97.42%). Adjust per-library after + # the first green run shows the real numbers. + name: Coverage gate (>= 95% per library) + needs: test + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + with: + pattern: coverage-* + path: coverage + + - name: Merge reports and enforce the gate + env: + THRESHOLD: '95' + run: | + python3 - <<'PY' + import glob + import os + import sys + import xml.etree.ElementTree as ET + + LIBS = [ + "Vali-Flow.Abstractions", "Vali-Flow", "Vali-Flow.InMemory", "Vali-Flow.Sql", + "Vali-Flow.NoSql", "Vali-Flow.NoSql.MongoDB", "Vali-Flow.NoSql.Elasticsearch", + "Vali-Flow.NoSql.Redis", "Vali-Flow.NoSql.DynamoDB", "Vali-Flow.NoSql.Couchbase", + "Vali-Flow.NoSql.CosmosDb", "Vali-Flow.NoSql.Firestore", + ] + THRESHOLD = float(os.environ["THRESHOLD"]) + OSES = ["ubuntu-latest", "windows-latest"] + TFMS = ["net8.0", "net9.0"] + + missing = [ + f"coverage-{os_name}-{tfm}" + for os_name in OSES + for tfm in TFMS + if not glob.glob(f"coverage/coverage-{os_name}-{tfm}/**/coverage.cobertura.xml", recursive=True) + ] + + lines = {lib: {} for lib in LIBS} + reports = glob.glob("coverage/**/coverage.cobertura.xml", recursive=True) + for path in reports: + for package in ET.parse(path).getroot().iter("package"): + store = lines.get(package.get("name")) + if store is None: + continue + for cls in package.iter("class"): + parts = cls.get("filename").replace("\\", "/").split("/") + file_key = "/".join(parts[-2:]) + for line in cls.iter("line"): + key = (file_key, int(line.get("number"))) + store[key] = max(store.get(key, 0), int(line.get("hits"))) + + rows = ["| Library | Lines | Covered | Line coverage | Gate |", "|---|---:|---:|---:|:---:|"] + failed = [] + for lib in LIBS: + total = len(lines[lib]) + covered = sum(1 for hits in lines[lib].values() if hits > 0) + pct = 100.0 * covered / total if total else 0.0 + ok = total > 0 and pct >= THRESHOLD + if not ok: + failed.append(lib) + rows.append(f"| {lib} | {total} | {covered} | {pct:.1f}% | {'pass' if ok else 'FAIL'} |") + + cells = ", ".join(f"{o} / {t}" for o in OSES for t in TFMS) + report = (f"### Unit-test line coverage (gate >= {THRESHOLD:g}%, {len(reports)} reports merged)\n\n" + + "\n".join(rows) + + f"\n\nExpected cells: {cells}\n" + + (f"\nMissing reports: {', '.join(missing)}\n" if missing else "\nAll 4 OS x TFM reports present.\n")) + print(report) + with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as handle: + handle.write(report + "\n") + if missing: + sys.exit("Coverage gate failed: missing reports for " + ", ".join(missing)) + if failed: + sys.exit("Coverage gate failed for: " + ", ".join(failed)) + PY + + pack: + name: Pack NuGet packages + needs: build + runs-on: ubuntu-latest + env: + VERSION_SUFFIX: ${{ inputs.version-suffix }} + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 8.0.x + 9.0.x + + - name: Apply the prerelease label + if: ${{ inputs.version-suffix != '' }} + run: | + if ! [[ "$VERSION_SUFFIX" =~ ^[0-9A-Za-z.-]+$ ]]; then + echo "::error::version-suffix may only contain letters, digits, dots and hyphens" + exit 1 + fi + cat > Directory.Build.targets <<'XML' + + + $(Version)-$(PrereleaseLabel) + + + XML + + - name: Pack every package in dependency order + run: | + for project in Vali-Flow.Abstractions Vali-Flow Vali-Flow.InMemory Vali-Flow.Sql Vali-Flow.NoSql Vali-Flow.NoSql.MongoDB Vali-Flow.NoSql.Elasticsearch Vali-Flow.NoSql.Redis Vali-Flow.NoSql.DynamoDB Vali-Flow.NoSql.Couchbase Vali-Flow.NoSql.CosmosDb Vali-Flow.NoSql.Firestore; do + dotnet pack "$project/$project.csproj" -c Release -o artifacts ${VERSION_SUFFIX:+-p:PrereleaseLabel="$VERSION_SUFFIX"} + done + + - name: Verify package contents + run: | + python3 - <<'PY' + import glob + import sys + import xml.etree.ElementTree as ET + import zipfile + + PACKAGES = { + "Vali-Flow.Abstractions", "Vali-Flow", "Vali-Flow.InMemory", "Vali-Flow.Sql", + "Vali-Flow.NoSql", "Vali-Flow.NoSql.MongoDB", "Vali-Flow.NoSql.Elasticsearch", + "Vali-Flow.NoSql.Redis", "Vali-Flow.NoSql.DynamoDB", "Vali-Flow.NoSql.Couchbase", + "Vali-Flow.NoSql.CosmosDb", "Vali-Flow.NoSql.Firestore", + } + TFMS = {"net8.0", "net9.0"} + + errors = [] + found = {} + for path in sorted(glob.glob("artifacts/*.nupkg")): + with zipfile.ZipFile(path) as archive: + names = archive.namelist() + root = ET.fromstring(archive.read(next(n for n in names if n.endswith(".nuspec")))) + ns = {"n": root.tag.split("}")[0].strip("{")} + pid = root.find("n:metadata/n:id", ns).text + version = root.find("n:metadata/n:version", ns).text + libs = {n.split("/")[1] for n in names if n.startswith("lib/") and n.endswith(".dll")} + found[pid] = (version, libs) + + for pid in sorted(PACKAGES - set(found)): + errors.append(f"{pid}: package missing from artifacts/") + for pid, (version, libs) in sorted(found.items()): + if libs != TFMS: + errors.append(f"{pid} {version}: lib/ has {sorted(libs)}, expected {sorted(TFMS)}") + print(f"{pid} {version}: lib {sorted(libs)}") + if errors: + sys.exit("Package check failed:\n " + "\n ".join(errors)) + print("Package check passed.") + PY + + - name: Upload packages + uses: actions/upload-artifact@v4 + with: + name: nuget-packages + path: artifacts/* + if-no-files-found: error + retention-days: 14 + + ci-ok: + name: CI OK + if: always() + needs: [build, test, coverage, pack] + runs-on: ubuntu-latest + steps: + - name: Every job must have succeeded + env: + RESULTS: ${{ toJSON(needs.*.result) }} + run: | + echo "$RESULTS" + if echo "$RESULTS" | grep -Eq '"(failure|cancelled|skipped)"'; then + exit 1 + fi diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..6b7ee5e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,133 @@ +name: Release + +# Manual only. By default it runs the full CI (net8.0/net9.0 on Linux and Windows) and uploads the +# packed NuGet packages as a workflow artifact; it publishes NOTHING. Publishing needs BOTH +# `publish: true` and an approval of the `nuget` environment (Settings > Environments > nuget > +# Required reviewers), and uses the NUGET_API_KEY secret of that environment. +# +# Publication order — 3 waves, because this repo has a 2-level dependency chain on top of the core: +# Wave 1: Vali-Flow.Abstractions alone. +# Wave 2: Vali-Flow, Vali-Flow.InMemory, Vali-Flow.Sql, Vali-Flow.NoSql (all depend on Abstractions). +# Wave 3: the 7 NoSQL provider packages (all depend on Vali-Flow.NoSql from wave 2). +# Each wave waits for NuGet.org to index the package the next wave needs before proceeding. +on: + workflow_dispatch: + inputs: + version-suffix: + description: Prerelease label appended to every package version, for example rc.1 (empty = versions from the csproj files) + type: string + required: false + default: '' + publish: + description: Publish the packages to NuGet.org after the approval of the nuget environment + type: boolean + default: false + +permissions: + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + ci: + name: CI (build, test on net8.0/net9.0, coverage gate, pack) + uses: ./.github/workflows/ci.yml + with: + version-suffix: ${{ inputs.version-suffix }} + + publish: + name: Publish to NuGet (needs approval) + needs: ci + if: ${{ inputs.publish }} + runs-on: ubuntu-latest + environment: nuget + env: + NUGET_SOURCE: https://api.nuget.org/v3/index.json + steps: + - uses: actions/download-artifact@v4 + with: + name: nuget-packages + path: artifacts + + - name: Every package must contain net8.0 and net9.0 + run: | + for package in artifacts/*.nupkg; do + for tfm in net8.0 net9.0; do + unzip -l "$package" | grep -q "lib/$tfm/" || { echo "::error::$package has no lib/$tfm"; exit 1; } + done + done + + - name: Check NUGET_API_KEY is configured + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + if [ -z "$NUGET_API_KEY" ]; then + echo "::error::NUGET_API_KEY is not set in the nuget environment" + exit 1 + fi + + # ---- Wave 1: Vali-Flow.Abstractions alone ---- + - name: 'Wave 1: push Vali-Flow.Abstractions' + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + # Vali-Flow.Abstractions is the only package whose id is followed by a version digit + # among files matching "Vali-Flow.Abstractions.*" (there is no other package with that + # prefix), so a plain glob is unambiguous here. + dotnet nuget push artifacts/Vali-Flow.Abstractions.[0-9]*.nupkg --source "$NUGET_SOURCE" --api-key "$NUGET_API_KEY" --skip-duplicate + + - name: 'Wave 1: wait until NuGet.org lists Vali-Flow.Abstractions' + run: | + pkg=$(basename artifacts/Vali-Flow.Abstractions.[0-9]*.nupkg .nupkg) + version=$(echo "${pkg#Vali-Flow.Abstractions.}" | tr '[:upper:]' '[:lower:]') + for attempt in $(seq 1 40); do + if curl -fsS "https://api.nuget.org/v3-flatcontainer/vali-flow.abstractions/index.json" | grep -q "\"$version\""; then + echo "Vali-Flow.Abstractions $version is indexed" + exit 0 + fi + echo "attempt $attempt/40: Vali-Flow.Abstractions $version not indexed yet" + sleep 30 + done + echo "::error::Vali-Flow.Abstractions $version was not indexed in time; re-run this job (--skip-duplicate makes it safe)" + exit 1 + + # ---- Wave 2: Vali-Flow, Vali-Flow.InMemory, Vali-Flow.Sql, Vali-Flow.NoSql ---- + - name: 'Wave 2: push Vali-Flow, Vali-Flow.InMemory, Vali-Flow.Sql, Vali-Flow.NoSql' + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + # Vali-Flow.[0-9]* matches only the main package (not Vali-Flow.InMemory.*, Vali-Flow.Sql.*, + # or Vali-Flow.NoSql.* — those have a literal "." before a letter, not a digit). + for pattern in 'Vali-Flow.[0-9]*' 'Vali-Flow.InMemory.[0-9]*' 'Vali-Flow.Sql.[0-9]*' 'Vali-Flow.NoSql.[0-9]*'; do + dotnet nuget push "artifacts/$pattern.nupkg" --source "$NUGET_SOURCE" --api-key "$NUGET_API_KEY" --skip-duplicate + done + + - name: 'Wave 2: wait until NuGet.org lists Vali-Flow.NoSql' + run: | + # Only Vali-Flow.NoSql gates wave 3 — the 7 providers depend on it, not on Vali-Flow/InMemory/Sql. + pkg=$(basename artifacts/Vali-Flow.NoSql.[0-9]*.nupkg .nupkg) + version=$(echo "${pkg#Vali-Flow.NoSql.}" | tr '[:upper:]' '[:lower:]') + for attempt in $(seq 1 40); do + if curl -fsS "https://api.nuget.org/v3-flatcontainer/vali-flow.nosql/index.json" | grep -q "\"$version\""; then + echo "Vali-Flow.NoSql $version is indexed" + exit 0 + fi + echo "attempt $attempt/40: Vali-Flow.NoSql $version not indexed yet" + sleep 30 + done + echo "::error::Vali-Flow.NoSql $version was not indexed in time; re-run this job (--skip-duplicate makes it safe)" + exit 1 + + # ---- Wave 3: the 7 NoSQL provider packages ---- + - name: 'Wave 3: push the 7 NoSQL provider packages' + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + for package in artifacts/Vali-Flow.NoSql.*.nupkg; do + case "$(basename "$package")" in + Vali-Flow.NoSql.[0-9]*) continue ;; # already pushed in wave 2 + esac + dotnet nuget push "$package" --source "$NUGET_SOURCE" --api-key "$NUGET_API_KEY" --skip-duplicate + done diff --git a/.gitignore b/.gitignore index feb2c5a..bd8c8c1 100644 --- a/.gitignore +++ b/.gitignore @@ -404,3 +404,8 @@ FodyWeavers.xsd .claude/ claude-*.md CLAUDE.md +.claudeignore +.guardian.json +.codegraph/ + +.superpowers/ diff --git a/CHANGELOG.md b/CHANGELOG.md index a15f550..08584d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,35 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and ## [Unreleased] +### Added + +- **`Vali-Flow.NoSql.Couchbase`, `Vali-Flow.NoSql.CosmosDb`, `Vali-Flow.NoSql.Firestore`** — three new NoSQL translator packages, same pattern as the existing MongoDB/DynamoDB/Elasticsearch/Redis adapters (pure `ValiFlow` expression tree → native query/filter translators, no connection or execution concerns). +- **`GenericRepository`** (`Vali-Flow`) — a thin repository wrapping `ValiFlowEvaluator` with `GetById`/`GetAll`/`GetPaged`/`Add`/`Update`/`Delete`/`SaveChanges`, for consumers who want a conventional repository surface instead of calling the evaluator directly. +- **`ValiFlowDiagnostics`** (`Vali-Flow.Abstractions`) — shared `ActivitySource`-based `StartActivity`/`RecordException` helper for OpenTelemetry-compatible tracing, now wired through the EF Core evaluator, `Vali-Flow.InMemory`, `Vali-Flow.Sql`'s six builders, and the Mongo/DynamoDB/Elasticsearch/Redis translators. +- EF Core benchmark using the `EFCore.InMemory` provider (`Vali-Flow.Benchmarks`). +- `SqlInsertBuilder`/`SqlUpdateBuilder.SetAllFrom(entity, exclude...)` — reflection-based bulk column mapper. + +### Fixed + +- **Security — SQL identifier injection**: `Vali-Flow.Sql`'s builders interpolated table/schema/type names directly; added `SqlIdentifierGuard` (regex whitelist) validating all identifiers before interpolation. +- **Security — RediSearch query injection**: `Vali-Flow.NoSql.Redis` didn't escape RediSearch query-syntax special characters (e.g. `)`/`|`) in `LIKE` patterns before wrapping them in wildcards, allowing query-structure injection. Now escaped before wildcarding. +- **`Vali-Flow.NoSql` (Mongo/Elasticsearch)**: closure-captured `null` values in a `ValiFlow` condition weren't translated to the same `NullNode` as a literal `null`, producing inconsistent filters between `.EqualTo(x => x.Prop, someNullVariable)` and `.EqualTo(x => x.Prop, null)`. +- **`Vali-Flow.NoSql.Redis`**: `customConverter` wasn't applied in `VisitComparison`/numeric `VisitIn`, silently ignoring custom type mappings for comparison and `IN` conditions. +- **`Vali-Flow.NoSql.Elasticsearch`**: swallowed inner exception in `ToDouble` conversion — failures surfaced as a generic error with no root cause. +- **`Vali-Flow.NoSql` (Mongo/Elasticsearch)**: unbounded `IN` value lists could exceed the engine's own limits; added `MaxInValues` caps (Mongo 10,000; Elasticsearch 65,536, matching `index.max_terms_count`). +- **`Vali-Flow.NoSql.Couchbase`**: `decimal` values were bound as N1QL string literals instead of native numbers. +- **`Vali-Flow.Sql`**: `OrIgnore`/`OrReplace` dialect guard bug, `Set()`-after-`SelectFrom()` silent data loss, `Where()` double-call silently overwriting the first condition instead of combining — all fixed. Added `AllowDeleteUnmatched()` guard required before `WhenNotMatchedBySourceDelete` in `SqlMergeBuilder` (prevents accidental unguarded deletes in a MERGE). +- **`Vali-Flow` (EF Core evaluator)**: `UpsertRangeAsync` dropped entries on duplicate keys (list accumulator instead of dictionary) — fixed to a dictionary accumulator. `UpsertRangeAsync.PartitionUpsertRange` could discard a tracked entity's primary key — now preserved. `BulkInsertOrUpdateAsync` could race under concurrent calls for the same entity type + key columns — calls are now serialized per that combination. +- **`Vali-Flow` (EF Core evaluator) — bulk upsert contention under concurrency**: replaced the ad-hoc retry with a generic transient-retry policy (`BulkUpsertRetryPolicy`) covering SQL Server, PostgreSQL, MySQL, and SQLite, gated per table (not per `UpdateByProperties` key set) to avoid serializing unrelated upserts against each other. Retry budget raised in two steps (4 → 7 → 12 attempts) based on observed contention under load. +- **`Vali-Flow.InMemory`**: `Update(entity, externalList)` could leak the updated entity into the internal store on a later bare `SaveChanges()` call. + +### Changed + +- **`Vali-Flow.InMemory`**: `ValiFlowEvaluator` (904 lines) split into `Bridge`/`Read`/`Write`/`Grouped` partial files; no public API change. +- **`Vali-Flow` (EF Core evaluator)**: query-construction logic extracted from `ValiFlowEvaluator` into a dedicated `QuerySpecificationBuilder` (single-responsibility split, no public API change). +- EF Core evaluator test coverage raised from 74.37% to 97.42%. +- Eliminated flaky `Activity`-capture tests across the `Sql`/EF-Core/`InMemory` test assemblies (timing-dependent assertions replaced with deterministic capture). + --- ## Vali-Flow — 1.3.3 diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 8dd9d88..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,124 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -**Vali-Flow** is a .NET library ecosystem that simplifies data access in Entity Framework Core applications via a fluent specification API. It is distributed as three independent NuGet packages, all built on top of **Vali-Flow.Core** (the expression tree builder — maintained in a separate repository at `/Users/feliperafaelmontenegro/RiderProjects/Vali-Flow.Core`). - -| Package | Version | Purpose | -|---------|---------|---------| -| `Vali-Flow` | 1.1.0 | EF Core evaluator + specification classes | -| `Vali-Flow.InMemory` | 1.0.0 | Synchronous in-memory evaluator (testing/caching) | -| `Vali-Flow.Sql` | 1.0.0 | Expression → parameterized SQL translator (Dapper/ADO.NET) | - -## Vali-Flow.Core Dependency - -All packages depend on **Vali-Flow.Core**, which provides `ValiFlow` (the fluent expression builder) and `ValiSort`. - -- All three packages (`Vali-Flow`, `Vali-Flow.InMemory`, `Vali-Flow.Sql`) reference Core via local `ProjectReference` pointing to `/Users/feliperafaelmontenegro/RiderProjects/Vali-Flow.Core/Vali-Flow.Core/Vali-Flow.Core.csproj`. -- **Do not change these to NuGet references yet** — Core v2.6.0 has not been published to NuGet. Once deployed, replace each `ProjectReference` with ``. -- **Current local Core version is 2.6.0** (net8.0 + net9.0, 911 tests). Core was extensively refactored: bugs fixed, new methods added (IsInEnum, IsDefault, IsCreditCard, IsIPv4/IPv6, IsHexColor, IsSlug, WithMessage(Func), IsLastDayOfMonth, EF Core-safe DateOnly/DateTimeOffset methods). - -## Build & Pack Commands - -```bash -# Build the full solution -dotnet build - -# Build in release -dotnet build --configuration Release - -# Pack individual packages -dotnet pack Vali-Flow/Vali-Flow.csproj --configuration Release -dotnet pack Vali-Flow.InMemory/Vali-Flow.InMemory.csproj --configuration Release -dotnet pack Vali-Flow.Sql/Vali-Flow.Sql.csproj --configuration Release -``` - -> There are currently no automated tests in this repo. The `vali-flow-test/` project is a console demo app, not a test suite. - -## Architecture - -### Package Structure - -``` -Vali-Flow.Core (local — /Users/feliperafaelmontenegro/RiderProjects/Vali-Flow.Core) - ↓ (ProjectReference — all three packages) -┌──────┴───────────────────────────────┐ -│ Vali-Flow (EF Core, async) │ -│ Vali-Flow.InMemory (sync) │ -│ Vali-Flow.Sql (Dapper/ADO.NET) │ -└──────────────────────────────────────┘ -``` - -### Vali-Flow (Main Package) - -**Entry point:** `ValiFlowEvaluator` — a sealed class taking a `DbContext`. Implements `IEvaluatorRead` + `IEvaluatorWrite`. - -**Specifications:** -``` -ISpecification - └─ IBasicSpecification → BasicSpecification (filter + includes + EF options) - └─ IQuerySpecification → QuerySpecification (+ ordering + pagination + top) -``` - -`BasicSpecification` holds: `ValiFlow` filter, `List>` includes, and EF Core hints (AsNoTracking, AsSplitQuery, IgnoreQueryFilters). - -`QuerySpecification` adds: primary `IEfOrderBy`, secondary `List>`, page/pageSize/top, and `ValiSort`. - -**Options** (in `Classes/Options/`): `EfInclude`, `EfOrderBy`, `EfOrderThenBy` — all sealed, generic over the property type. - -**Evaluator read methods:** EvaluateAsync (single entity), EvaluateAnyAsync, EvaluateCountAsync, EvaluateGetFirstAsync, EvaluateGetLastAsync, EvaluateGetFirstFailedAsync, EvaluateGetLastFailedAsync, EvaluateQueryAsync, EvaluateQueryFailedAsync, EvaluateDistinctAsync, EvaluateDuplicatesAsync, aggregate methods (Min/Max/Average/Sum), grouped methods (EvaluateGroupedAsync, EvaluateCountByGroupAsync, EvaluateSumByGroupAsync, EvaluateMinByGroupAsync, EvaluateMaxByGroupAsync, EvaluateAverageByGroupAsync, EvaluateTopByGroupAsync, EvaluateAggregateAsync). - -**Evaluator write methods:** AddAsync, UpdateAsync, DeleteAsync, AddRangeAsync, UpdateRangeAsync, DeleteRangeAsync, DeleteByConditionAsync, UpsertAsync, UpsertRangeAsync, BulkInsertAsync, BulkUpdateAsync, BulkDeleteAsync, BulkInsertOrUpdateAsync, ExecuteTransactionAsync, SaveChangesAsync. - -### Vali-Flow.InMemory - -**Entry point:** `ValiFlowEvaluator` — synchronous, operates on `IEnumerable`. Takes `initialData`, an optional `ValiFlow`, and a `Func getId`. Extends `EvaluatorBase`. - -Mirrors the EF Core evaluator API but synchronous and without a DbContext. Useful for unit testing and caching layers. - -### Vali-Flow.Sql - -**Entry point:** `ValiFlowSqlExtensions` — provides `.ToSql(dialect)` extension method on `ValiFlow`, returning a `SqlResult` (with `Sql` string and `IReadOnlyDictionary Parameters`). - -**Translator:** `ExpressionToSqlVisitor` (sealed, internal) — an `ExpressionVisitor` that walks expression trees and emits dialect-specific SQL. - -**Dialects (all sealed):** -- `SqlServerDialect` — `@param`, `[col]`, `LOWER()` -- `PostgreSqlDialect` — `@param`, `"col"`, native `ILIKE` -- `MySqlDialect` — `@param`, `` `col` ``, case-insensitive `LIKE` -- `SqliteDialect` — `@param`, `"col"`, `LOWER()` - -`SqlResult.ApplyTo(IDbCommand)` applies parameters directly to an ADO.NET command. - -## Key Design Decisions - -- **Specification pattern**: query criteria are decoupled from the evaluator — build a spec, pass it to the evaluator. -- **Deferred saves**: pass `saveChanges: false` to batch operations and call `SaveChangesAsync()` once. -- **Bulk operations**: `BulkInsert/Update/Delete/InsertOrUpdate` delegate to `EFCore.BulkExtensions` — pass a `BulkConfig` to control batch size and identity output. -- **`negateCondition` parameter**: all read methods accept this flag to invert the `ValiFlow` filter (logical NOT). -- **`ValiSort`**: sorting helper from Vali-Flow.Core; used by `QuerySpecification` for dynamic/reflection-based ordering. -- **No xUnit tests yet**: testing is done via the `vali-flow-test` console app. A proper test project (xUnit + FluentAssertions) should be added following the same pattern as `Vali-Flow.Core.Tests`. - -## CRITICAL: Partial Classes & Modifiers - -⚠️ **IMPORTANT WHEN MODIFYING ValiFlowEvaluator:** - -Both `ValiFlowEvaluator` (Vali-Flow) and `ValiFlowEvaluator` (InMemory) are **`partial` classes split across multiple files**: - -**Vali-Flow:** -- `ValiFlowEvaluator.cs` — main declaration (MUST have `public partial class`) -- `ValiFlowEvaluator.Read.cs` — read operations -- `ValiFlowEvaluator.Write.cs` — write operations -- `ValiFlowEvaluator.Aggregates.cs` — aggregates - -**InMemory:** -- Similar split structure - -**GOTCHA:** When removing modifiers (like `sealed`), ALWAYS ensure the main declaration includes `partial`. Forgetting this causes `CS0260: Missing partial modifier` compilation error even though the class looks correct in isolation. - -**Process for modifying these classes:** -1. Edit ValiFlowEvaluator.cs and verify: `public partial class ValiFlowEvaluator` -2. If removing sealed or other modifiers, rebuild with `dotnet build` BEFORE packing NuGet -3. After rebuild succeeds, generate NuGet with `dotnet pack --no-build` diff --git a/README.md b/README.md index 1375dbd..75862ca 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Vali-Flow is a comprehensive .NET library ecosystem for building reusable, compo All built on **Vali-Flow.Core** — a lightweight expression builder with zero additional dependencies. -**Supported platforms:** .NET 8.0, .NET 9.0 +**Supported platforms:** .NET 8.0, .NET 9.0 — all packages also run unmodified on **.NET 10** thanks to .NET's forward compatibility (a library built for an earlier TFM runs fine under a newer runtime). --- @@ -83,18 +83,21 @@ var sqlOrders = await connection.QueryAsync( | Package | Purpose | Target | Version | |---------|---------|--------|---------| -| **Vali-Flow** | EF Core async evaluator + specifications (read/write) | `DbContext` | [1.1.0](https://www.nuget.org/packages/Vali-Flow) | -| **Vali-Flow.InMemory** | Synchronous in-memory evaluator for testing & caching | `IEnumerable` | [1.0.0](https://www.nuget.org/packages/Vali-Flow.InMemory) | -| **Vali-Flow.Sql** | SQL query builder for parameterized queries | Dapper / ADO.NET | [1.0.0](https://www.nuget.org/packages/Vali-Flow.Sql) | +| **Vali-Flow** | EF Core async evaluator + specifications (read/write) | `DbContext` | [1.3.4](https://www.nuget.org/packages/Vali-Flow) | +| **Vali-Flow.InMemory** | Synchronous in-memory evaluator for testing & caching | `IEnumerable` | [1.1.5](https://www.nuget.org/packages/Vali-Flow.InMemory) | +| **Vali-Flow.Sql** | SQL query builder for parameterized queries | Dapper / ADO.NET | [1.1.1](https://www.nuget.org/packages/Vali-Flow.Sql) | ### NoSQL Packages | Package | Database | Output Type | Version | |---------|----------|-------------|---------| -| **Vali-Flow.NoSql.MongoDB** | MongoDB | `BsonDocument` | [1.0.0](https://www.nuget.org/packages/Vali-Flow.NoSql.MongoDB) | -| **Vali-Flow.NoSql.Elasticsearch** | Elasticsearch | `Query` (Elastic.Clients) | [1.0.0](https://www.nuget.org/packages/Vali-Flow.NoSql.Elasticsearch) | -| **Vali-Flow.NoSql.Redis** | Redis (RediSearch) | Query string | [1.0.0](https://www.nuget.org/packages/Vali-Flow.NoSql.Redis) | -| **Vali-Flow.NoSql.DynamoDB** | AWS DynamoDB | `DynamoFilterExpression` | [1.0.0](https://www.nuget.org/packages/Vali-Flow.NoSql.DynamoDB) | +| **Vali-Flow.NoSql.MongoDB** | MongoDB | `BsonDocument` | [1.1.0](https://www.nuget.org/packages/Vali-Flow.NoSql.MongoDB) | +| **Vali-Flow.NoSql.Elasticsearch** | Elasticsearch | `Query` (Elastic.Clients) | [1.1.0](https://www.nuget.org/packages/Vali-Flow.NoSql.Elasticsearch) | +| **Vali-Flow.NoSql.Redis** | Redis (RediSearch) | Query string | [1.1.0](https://www.nuget.org/packages/Vali-Flow.NoSql.Redis) | +| **Vali-Flow.NoSql.DynamoDB** | AWS DynamoDB | `DynamoFilterExpression` | [1.1.0](https://www.nuget.org/packages/Vali-Flow.NoSql.DynamoDB) | +| **Vali-Flow.NoSql.Couchbase** | Couchbase | N1QL WHERE fragment + parameters | [1.0.0](https://www.nuget.org/packages/Vali-Flow.NoSql.Couchbase) | +| **Vali-Flow.NoSql.CosmosDb** | Azure Cosmos DB (SQL API) | SQL WHERE fragment + parameters | [1.0.0](https://www.nuget.org/packages/Vali-Flow.NoSql.CosmosDb) | +| **Vali-Flow.NoSql.Firestore** | Google Cloud Firestore | `Filter` (Google.Cloud.Firestore) | [1.0.0](https://www.nuget.org/packages/Vali-Flow.NoSql.Firestore) | ### Architecture @@ -103,13 +106,16 @@ Vali-Flow.Core (expression builder — ValiFlow) │ ├─── Vali-Flow (EF Core async) ├─── Vali-Flow.InMemory (sync in-memory) - ├─── Vali-Flow.Sql (SQL: SQL Server, PostgreSQL, MySQL, SQLite) + ├─── Vali-Flow.Sql (SQL: SQL Server, PostgreSQL, MySQL, SQLite, Oracle) │ └─── Vali-Flow.NoSql ├─── Vali-Flow.NoSql.MongoDB (MongoDB BSON) ├─── Vali-Flow.NoSql.Elasticsearch (Elasticsearch Query DSL) ├─── Vali-Flow.NoSql.Redis (RediSearch) - └─── Vali-Flow.NoSql.DynamoDB (DynamoDB filter expressions) + ├─── Vali-Flow.NoSql.DynamoDB (DynamoDB filter expressions) + ├─── Vali-Flow.NoSql.Couchbase (N1QL / SQL++) + ├─── Vali-Flow.NoSql.CosmosDb (Cosmos DB SQL API) + └─── Vali-Flow.NoSql.Firestore (Firestore native Filter) ``` --- diff --git a/Vali-Flow.Abstractions.Tests/Diagnostics/ValiFlowDiagnosticsTests.cs b/Vali-Flow.Abstractions.Tests/Diagnostics/ValiFlowDiagnosticsTests.cs new file mode 100644 index 0000000..732a4af --- /dev/null +++ b/Vali-Flow.Abstractions.Tests/Diagnostics/ValiFlowDiagnosticsTests.cs @@ -0,0 +1,73 @@ +using System.Diagnostics; +using Vali_Flow.Abstractions.Diagnostics; + +namespace Vali_Flow.Abstractions.Tests.Diagnostics; + +public sealed class ValiFlowDiagnosticsTests +{ + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void StartActivity_NoListenerAttached_ReturnsNull() + { + // Without a listener, ActivitySource.StartActivity short-circuits to null — near-zero cost. + Activity? activity = ValiFlowDiagnostics.StartActivity("Test.Operation"); + + activity.Should().BeNull(); + } + + [Fact] + public void StartActivity_WithListener_SetsTagAndEntityType() + { + using var listener = AttachListener(); + + using Activity? activity = ValiFlowDiagnostics.StartActivity("Test.Operation", tag: "MyReport", entityType: "User"); + + activity.Should().NotBeNull(); + activity!.GetTagItem("vali_flow.tag").Should().Be("MyReport"); + activity.GetTagItem("vali_flow.entity_type").Should().Be("User"); + } + + [Fact] + public void StartActivity_WithoutTagOrEntityType_SetsNoExtraTags() + { + using var listener = AttachListener(); + + using Activity? activity = ValiFlowDiagnostics.StartActivity("Test.Operation"); + + activity.Should().NotBeNull(); + activity!.GetTagItem("vali_flow.tag").Should().BeNull(); + activity.GetTagItem("vali_flow.entity_type").Should().BeNull(); + } + + [Fact] + public void RecordException_NullActivity_DoesNothing() + { + var act = () => ValiFlowDiagnostics.RecordException(null, new InvalidOperationException("boom")); + + act.Should().NotThrow(); + } + + [Fact] + public void RecordException_SetsErrorStatusAndExceptionEvent() + { + using var listener = AttachListener(); + using Activity? activity = ValiFlowDiagnostics.StartActivity("Test.Operation"); + + var ex = new InvalidOperationException("boom"); + ValiFlowDiagnostics.RecordException(activity, ex); + + activity!.Status.Should().Be(ActivityStatusCode.Error); + activity.StatusDescription.Should().Be("boom"); + activity.Events.Should().ContainSingle(e => e.Name == "exception"); + } +} diff --git a/Vali-Flow.Abstractions.Tests/ExpressionInspectorTests.cs b/Vali-Flow.Abstractions.Tests/ExpressionInspectorTests.cs new file mode 100644 index 0000000..18a4fac --- /dev/null +++ b/Vali-Flow.Abstractions.Tests/ExpressionInspectorTests.cs @@ -0,0 +1,144 @@ +using System.Linq.Expressions; +using Vali_Flow.Abstractions.Helpers; + +namespace Vali_Flow.Abstractions.Tests; + +public sealed class ExpressionInspectorTests +{ + private sealed class TestEntity + { + public int Age { get; set; } + public string? Name { get; set; } + } + + // ── IsColumnExpression ────────────────────────────────────────────── + + [Fact] + public void IsColumnExpression_DirectMember_ReturnsTrue() + { + Expression> expr = x => x.Age; + ExpressionInspector.IsColumnExpression(expr.Body).Should().BeTrue(); + } + + [Fact] + public void IsColumnExpression_MemberWrappedInConvert_ReturnsTrue() + { + Expression> expr = x => x.Age; + // x.Age boxed to object produces Convert(MemberExpression) + ExpressionInspector.IsColumnExpression(expr.Body).Should().BeTrue(); + } + + [Fact] + public void IsColumnExpression_Constant_ReturnsFalse() + { + Expression> expr = _ => 18; + ExpressionInspector.IsColumnExpression(expr.Body).Should().BeFalse(); + } + + [Fact] + public void IsColumnExpression_Null_ThrowsArgumentNullException() + { + var act = () => ExpressionInspector.IsColumnExpression(null!); + act.Should().Throw(); + } + + // ── IsNullConstant ─────────────────────────────────────────────────── + + [Fact] + public void IsNullConstant_NullLiteral_ReturnsTrue() + { + Expression> expr = x => x.Name == null; + var binary = (BinaryExpression)expr.Body; + ExpressionInspector.IsNullConstant(binary.Right).Should().BeTrue(); + } + + [Fact] + public void IsNullConstant_NonNullConstant_ReturnsFalse() + { + Expression> expr = x => x.Name == "a"; + var binary = (BinaryExpression)expr.Body; + ExpressionInspector.IsNullConstant(binary.Right).Should().BeFalse(); + } + + [Fact] + public void IsNullConstant_Null_ThrowsArgumentNullException() + { + var act = () => ExpressionInspector.IsNullConstant(null!); + act.Should().Throw(); + } + + [Fact] + public void IsNullConstant_NullWrappedInConvertChecked_ReturnsTrue() + { + // Mirrors the ConvertChecked handling already present in IsColumnExpression. + var convertChecked = Expression.ConvertChecked(Expression.Constant(null, typeof(object)), typeof(string)); + ExpressionInspector.IsNullConstant(convertChecked).Should().BeTrue(); + } + + // ── EvaluateExpression ─────────────────────────────────────────────── + + [Fact] + public void EvaluateExpression_Constant_ReturnsValue() + { + Expression> expr = _ => 42; + ExpressionInspector.EvaluateExpression(expr.Body).Should().Be(42); + } + + [Fact] + public void EvaluateExpression_ClosureCapturedVariable_ReturnsRuntimeValue() + { + int captured = 7; + Expression> expr = _ => captured + 1; + ExpressionInspector.EvaluateExpression(expr.Body).Should().Be(8); + } + + [Fact] + public void EvaluateExpression_ExpressionReferencingUnboundParameter_ThrowsInvalidOperationException() + { + Expression> expr = x => x.Age; + + var act = () => ExpressionInspector.EvaluateExpression(expr.Body); + + act.Should().Throw(); + } + + [Fact] + public void EvaluateExpression_Null_ThrowsArgumentNullException() + { + var act = () => ExpressionInspector.EvaluateExpression(null!); + + act.Should().Throw(); + } + + // ── FlipComparisonOperator ─────────────────────────────────────────── + + [Theory] + [InlineData(ExpressionType.GreaterThan, ExpressionType.LessThan)] + [InlineData(ExpressionType.GreaterThanOrEqual, ExpressionType.LessThanOrEqual)] + [InlineData(ExpressionType.LessThan, ExpressionType.GreaterThan)] + [InlineData(ExpressionType.LessThanOrEqual, ExpressionType.GreaterThanOrEqual)] + [InlineData(ExpressionType.Equal, ExpressionType.Equal)] + [InlineData(ExpressionType.NotEqual, ExpressionType.NotEqual)] + public void FlipComparisonOperator_ReturnsExpectedMirror(ExpressionType input, ExpressionType expected) + { + ExpressionInspector.FlipComparisonOperator(input).Should().Be(expected); + } + + [Fact] + public void FlipComparisonOperator_SemanticsPreserved_ConstantOnLeft() + { + // 18 < x.Age == x.Age > 18 + const int left = 18; + const int age = 25; + + bool original = left < age; + var flipped = ExpressionInspector.FlipComparisonOperator(ExpressionType.LessThan); + bool flippedResult = flipped switch + { + ExpressionType.GreaterThan => age > left, + _ => throw new InvalidOperationException("unexpected flip result") + }; + + flippedResult.Should().Be(original); + } +} diff --git a/Vali-Flow.Abstractions.Tests/Vali-Flow.Abstractions.Tests.csproj b/Vali-Flow.Abstractions.Tests/Vali-Flow.Abstractions.Tests.csproj new file mode 100644 index 0000000..619d5db --- /dev/null +++ b/Vali-Flow.Abstractions.Tests/Vali-Flow.Abstractions.Tests.csproj @@ -0,0 +1,28 @@ + + + + net9.0 + Vali_Flow.Abstractions.Tests + enable + enable + false + + + + + + + + + + + + + + + + + + + + diff --git a/Vali-Flow.Abstractions/Diagnostics/ValiFlowDiagnostics.cs b/Vali-Flow.Abstractions/Diagnostics/ValiFlowDiagnostics.cs new file mode 100644 index 0000000..62b2515 --- /dev/null +++ b/Vali-Flow.Abstractions/Diagnostics/ValiFlowDiagnostics.cs @@ -0,0 +1,63 @@ +using System.Diagnostics; + +namespace Vali_Flow.Abstractions.Diagnostics; + +/// +/// Shared for the whole Vali-Flow ecosystem. Every evaluator/translator +/// starts an per operation through — this is the +/// "tag"/observability hook across packages: no logging framework dependency, works out of the box +/// with any OpenTelemetry-compatible listener (Application Insights, Jaeger, Datadog, etc.), and does +/// nothing (near-zero cost) when no listener is attached. +/// +/// +/// To observe these activities, register a listener once at application startup, e.g. via +/// OpenTelemetry's AddSource("Vali-Flow"), or a minimal . +/// +public static class ValiFlowDiagnostics +{ + /// The name every Vali-Flow package shares. Use this with AddSource(...). + public const string SourceName = "Vali-Flow"; + + /// The shared instance used by every Vali-Flow package. + public static readonly ActivitySource Source = new(SourceName, "1.0.0"); + + /// + /// Starts an for a Vali-Flow operation (query evaluation, write, translation). + /// Returns null when no listener is attached — callers must null-check before using the result, + /// same as any call. + /// + /// The operation name, e.g. "Vali-Flow.EvaluateQueryAsync". + /// + /// Optional developer-supplied label (the "TagWith"-style tag) identifying why/where this + /// operation was triggered — set as the vali_flow.tag tag when present. + /// + /// Optional entity type name — set as the vali_flow.entity_type tag. + public static Activity? StartActivity(string operationName, string? tag = null, string? entityType = null) + { + Activity? activity = Source.StartActivity(operationName, ActivityKind.Internal); + if (activity == null) return null; + + if (tag != null) activity.SetTag("vali_flow.tag", tag); + if (entityType != null) activity.SetTag("vali_flow.entity_type", entityType); + + return activity; + } + + /// + /// Records a failed operation on the given activity: sets an error status and attaches an + /// OpenTelemetry-style exception event, then returns — the caller is still responsible + /// for rethrowing. Never swallows the exception. + /// + public static void RecordException(Activity? activity, Exception ex) + { + if (activity == null) return; + + activity.SetStatus(ActivityStatusCode.Error, ex.Message); + activity.AddEvent(new ActivityEvent("exception", tags: new ActivityTagsCollection + { + { "exception.type", ex.GetType().FullName }, + { "exception.message", ex.Message }, + { "exception.stacktrace", ex.StackTrace } + })); + } +} diff --git a/Vali-Flow.Abstractions/Helpers/ExpressionInspector.cs b/Vali-Flow.Abstractions/Helpers/ExpressionInspector.cs index 3226ad5..fdcb567 100644 --- a/Vali-Flow.Abstractions/Helpers/ExpressionInspector.cs +++ b/Vali-Flow.Abstractions/Helpers/ExpressionInspector.cs @@ -14,6 +14,8 @@ public static class ExpressionInspector /// public static bool IsColumnExpression(Expression expr) { + ArgumentNullException.ThrowIfNull(expr); + while (expr is UnaryExpression { NodeType: ExpressionType.Convert or ExpressionType.ConvertChecked } u) expr = u.Operand; @@ -25,20 +27,28 @@ public static bool IsColumnExpression(Expression expr) /// including null wrapped in Convert wrappers. /// public static bool IsNullConstant(Expression expr) - => expr is ConstantExpression { Value: null } - || (expr is UnaryExpression { NodeType: ExpressionType.Convert } u && IsNullConstant(u.Operand)); + { + ArgumentNullException.ThrowIfNull(expr); + + return expr is ConstantExpression { Value: null } + || (expr is UnaryExpression { NodeType: ExpressionType.Convert or ExpressionType.ConvertChecked } u + && IsNullConstant(u.Operand)); + } /// /// Evaluates a non-column expression (closure capture, constant, or computed value) /// to its runtime value. /// /// The evaluated value, or null for null literals. + /// Thrown when is null. /// /// Thrown when the expression cannot be evaluated to a constant value /// (e.g. it references a non-captured variable). /// public static object? EvaluateExpression(Expression expr) { + ArgumentNullException.ThrowIfNull(expr); + if (expr is ConstantExpression constant) return constant.Value; diff --git a/Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj b/Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj index 2e5ddd6..b914c86 100644 --- a/Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj +++ b/Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj @@ -14,7 +14,7 @@ git true Copyright © 2025 - FM. All rights reserved. - 1.1.0 + 1.2.0 VF_logo.png Vali-Flow.Abstractions Vali-Flow.Abstractions @@ -29,7 +29,9 @@ true snupkg - v1.1.0 — Enhanced documentation and internal contracts alignment with ecosystem refactor. + v1.2.0 — Add ValiFlowDiagnostics: a shared ActivitySource-based observability helper (StartActivity/RecordException) used across every Vali-Flow package for Activity-based tracing. No breaking changes. + +v1.1.0 — Enhanced documentation and internal contracts alignment with ecosystem refactor. diff --git a/Vali-Flow.Benchmarks/Benchmarks/EfCoreBenchmarks.cs b/Vali-Flow.Benchmarks/Benchmarks/EfCoreBenchmarks.cs new file mode 100644 index 0000000..b39d8bb --- /dev/null +++ b/Vali-Flow.Benchmarks/Benchmarks/EfCoreBenchmarks.cs @@ -0,0 +1,90 @@ +using BenchmarkDotNet.Attributes; +using BenchmarkDotNet.Engines; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Benchmarks.Models; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; + +namespace Vali_Flow.Benchmarks.Benchmarks; + +/// +/// Benchmarks for ValiFlowEvaluator<T> (Vali-Flow, EF Core package) against the EF Core +/// InMemory provider. Measures query-building + LINQ translation overhead vs. hand-written +/// LINQ-to-Entities, not real I/O (no real database is involved). +/// Baseline: filtered query enumeration. Paged/Count are secondary references. +/// +[MemoryDiagnoser] +public class EfCoreBenchmarks +{ + [Params(1_000, 10_000, 100_000)] + public int N; + + private BenchmarkDbContext _dbContext = null!; + private readonly Consumer _consumer = new(); + + private ValiFlowEvaluator _evaluator = null!; + private QuerySpecification _filterSpec = null!; + private QuerySpecification _pagedSpec = null!; + + [GlobalSetup] + public void Setup() + { + var options = new DbContextOptionsBuilder() + .UseInMemoryDatabase(databaseName: $"vali-flow-bench-{N}") + .Options; + + _dbContext = new BenchmarkDbContext(options); + _dbContext.Orders.AddRange(BenchmarkDataFactory.Generate(N)); + _dbContext.SaveChanges(); + + _evaluator = new ValiFlowEvaluator(_dbContext); + + _filterSpec = new QuerySpecification( + new ValiFlowQuery().IsTrue(o => o.IsActive)); + + _pagedSpec = new QuerySpecification( + new ValiFlowQuery().IsTrue(o => o.IsActive)) + .WithOrderBy(o => o.Id) + .WithPagination(1, 50); + } + + [GlobalCleanup] + public void Cleanup() => _dbContext.Dispose(); + + // ── Filter (baseline) ───────────────────────────────────────────────────── + + [Benchmark(Baseline = true)] + public void FilterAll_IsActive_Linq() => + _dbContext.Orders.Where(o => o.IsActive).Consume(_consumer); + + [Benchmark] + public async Task FilterAll_IsActive_ValiFlow() + { + var query = await _evaluator.EvaluateQueryAsync(_filterSpec); + query.Consume(_consumer); + } + + // ── Paged (reference — no ratio) ────────────────────────────────────────── + + [Benchmark] + public void Page1x50_IsActive_Linq() => + _dbContext.Orders.Where(o => o.IsActive).OrderBy(o => o.Id).Skip(0).Take(50).Consume(_consumer); + + [Benchmark] + public async Task Page1x50_IsActive_ValiFlow() + { + var result = await _evaluator.EvaluatePagedAsync(_pagedSpec); + return new PagedResultLength(result.Items.Count); + } + + // ── Count (reference — no ratio) ────────────────────────────────────────── + + [Benchmark] + public int Count_IsActive_Linq() => _dbContext.Orders.Count(o => o.IsActive); + + [Benchmark] + public Task Count_IsActive_ValiFlow() => _evaluator.EvaluateCountAsync(_filterSpec); + + public readonly record struct PagedResultLength(int Count); +} diff --git a/Vali-Flow.Benchmarks/Benchmarks/InMemoryAggregateBenchmarks.cs b/Vali-Flow.Benchmarks/Benchmarks/InMemoryAggregateBenchmarks.cs index c99a13c..a7c5e07 100644 --- a/Vali-Flow.Benchmarks/Benchmarks/InMemoryAggregateBenchmarks.cs +++ b/Vali-Flow.Benchmarks/Benchmarks/InMemoryAggregateBenchmarks.cs @@ -1,5 +1,4 @@ using BenchmarkDotNet.Attributes; -using BenchmarkDotNet.Engines; using Vali_Flow.Benchmarks.Models; using Vali_Flow.Core.Builder; using Vali_Flow.InMemory.Classes.Evaluators; @@ -16,8 +15,7 @@ public class InMemoryAggregateBenchmarks [Params(1_000, 10_000, 100_000)] public int N; - private List _data = null!; - private readonly Consumer _consumer = new(); + private List _data = null!; private ValiFlowEvaluator _evalIsActive = null!; diff --git a/Vali-Flow.Benchmarks/Models/BenchmarkDbContext.cs b/Vali-Flow.Benchmarks/Models/BenchmarkDbContext.cs new file mode 100644 index 0000000..20865c3 --- /dev/null +++ b/Vali-Flow.Benchmarks/Models/BenchmarkDbContext.cs @@ -0,0 +1,16 @@ +using Microsoft.EntityFrameworkCore; + +namespace Vali_Flow.Benchmarks.Models; + +/// +/// Minimal DbContext backed by the EF Core InMemory provider, used only to measure +/// ValiFlowEvaluator<T> query-building/translation overhead — not real I/O. +/// +public sealed class BenchmarkDbContext : DbContext +{ + public BenchmarkDbContext(DbContextOptions options) : base(options) + { + } + + public DbSet Orders => Set(); +} diff --git a/Vali-Flow.Benchmarks/Vali-Flow.Benchmarks.csproj b/Vali-Flow.Benchmarks/Vali-Flow.Benchmarks.csproj index 5e1a28f..6ed6d14 100644 --- a/Vali-Flow.Benchmarks/Vali-Flow.Benchmarks.csproj +++ b/Vali-Flow.Benchmarks/Vali-Flow.Benchmarks.csproj @@ -8,8 +8,10 @@ + + diff --git a/Vali-Flow.InMemory.Tests/AssemblyInfo.cs b/Vali-Flow.InMemory.Tests/AssemblyInfo.cs new file mode 100644 index 0000000..521adca --- /dev/null +++ b/Vali-Flow.InMemory.Tests/AssemblyInfo.cs @@ -0,0 +1,10 @@ +using Xunit; + +// ValiFlowInMemoryDiagnosticsTests asserts on System.Diagnostics.Activity captured via a process-wide +// ActivityListener on ValiFlowDiagnostics.Source, parenting each test's activities under a private +// root and filtering by ParentId. That reduces -- but does not fully eliminate -- cross-test +// collisions under xUnit's default test-class-level parallelism: the identical pattern was observed +// intermittently failing with "Sequence contains no matching element" in Vali-Flow.Sql.Tests (which +// has more Activity-asserting test classes competing concurrently). Disabling parallelization for +// this assembly removes that race at its source. +[assembly: CollectionBehavior(DisableTestParallelization = true)] diff --git a/Vali-Flow.InMemory.Tests/ValiFlowInMemoryDiagnosticsTests.cs b/Vali-Flow.InMemory.Tests/ValiFlowInMemoryDiagnosticsTests.cs new file mode 100644 index 0000000..e66f19c --- /dev/null +++ b/Vali-Flow.InMemory.Tests/ValiFlowInMemoryDiagnosticsTests.cs @@ -0,0 +1,137 @@ +using System.Diagnostics; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.Core.Builder; +using Vali_Flow.InMemory.Classes.Evaluators; +using Vali_Flow.InMemory.Tests.Models; + +namespace Vali_Flow.InMemory.Tests; + +public sealed class ValiFlowInMemoryDiagnosticsTests +{ + private static readonly List Seed = new() + { + new() { Id = 1, Name = "Apple", Category = "Fruit", Price = 1.5m, Stock = 100, IsActive = true }, + new() { Id = 2, Name = "Donut", Category = "Sweet", Price = 2.5m, Stock = 50, IsActive = false }, + }; + + private static ValiFlowEvaluator CreateEvaluator() + => new(Seed, null, p => p.Id); + + /// + /// Attaches a listener and parents every captured activity under a private root, so concurrently + /// running tests (xunit parallelizes test classes by default) can never pollute this test's capture + /// list even though they share the same process-wide . + /// + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); // becomes Activity.Current -> parents child activities + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root, string operationName) + => captured.Single(a => a.OperationName == operationName && a.ParentId == root.Id); + + [Fact] + public void EvaluateAny_WithTag_SetsTagAndEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + var evaluator = CreateEvaluator(); + var filter = new ValiFlow().IsTrue(p => p.IsActive); + + evaluator.EvaluateAny(valiFlow: filter, tag: "MyReport"); + + var activity = GetOwn(captured, root, "Vali-Flow.InMemory.EvaluateAny"); + activity.GetTagItem("vali_flow.tag").Should().Be("MyReport"); + activity.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestProduct)); + } + + [Fact] + public void EvaluateCount_WithoutTag_SetsNoTag() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + var evaluator = CreateEvaluator(); + + evaluator.EvaluateCount(); + + var activity = GetOwn(captured, root, "Vali-Flow.InMemory.EvaluateCount"); + activity.GetTagItem("vali_flow.tag").Should().BeNull(); + } + + [Fact] + public void EvaluateMin_NoMatchingEntities_RecordsErrorStatusAndRethrows() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + var evaluator = CreateEvaluator(); + // Filter matches nothing -> Min() on an empty int sequence throws InvalidOperationException. + var filter = new ValiFlow().IsTrue(p => p.Id == -1); + + Action act = () => evaluator.EvaluateMin(null, p => p.Stock, filter, tag: "Ingest"); + + act.Should().Throw(); + var activity = GetOwn(captured, root, "Vali-Flow.InMemory.EvaluateMin"); + activity.Status.Should().Be(ActivityStatusCode.Error); + activity.GetTagItem("vali_flow.tag").Should().Be("Ingest"); + activity.Events.Should().ContainSingle(e => e.Name == "exception"); + } + + [Fact] + public void EvaluateGrouped_WithTag_SetsTagAndEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + var evaluator = CreateEvaluator(); + + evaluator.EvaluateGrouped(null, p => p.Category, tag: "GroupReport"); + + var activity = GetOwn(captured, root, "Vali-Flow.InMemory.EvaluateGrouped"); + activity.GetTagItem("vali_flow.tag").Should().Be("GroupReport"); + activity.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestProduct)); + } + + [Fact] + public void EvaluateTopByGroup_InvalidCount_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + var evaluator = CreateEvaluator(); + + Action act = () => evaluator.EvaluateTopByGroup(null, p => p.Category, count: 0, tag: "BadCount"); + + act.Should().Throw(); + var activity = GetOwn(captured, root, "Vali-Flow.InMemory.EvaluateTopByGroup"); + activity.Status.Should().Be(ActivityStatusCode.Error); + } + + [Fact] + public void EvaluatePagedResult_InvalidPage_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + var evaluator = CreateEvaluator(); + + Action act = () => evaluator.EvaluatePagedResult(page: 0, tag: "BadPage"); + + act.Should().Throw(); + var activity = GetOwn(captured, root, "Vali-Flow.InMemory.EvaluatePagedResult"); + activity.Status.Should().Be(ActivityStatusCode.Error); + activity.GetTagItem("vali_flow.tag").Should().Be("BadPage"); + } +} diff --git a/Vali-Flow.InMemory.Tests/ValiFlowInMemoryWriteTests.cs b/Vali-Flow.InMemory.Tests/ValiFlowInMemoryWriteTests.cs index 0b69f17..a6606b1 100644 --- a/Vali-Flow.InMemory.Tests/ValiFlowInMemoryWriteTests.cs +++ b/Vali-Flow.InMemory.Tests/ValiFlowInMemoryWriteTests.cs @@ -179,6 +179,23 @@ public void Update_ToExplicitList_UpdatesListImmediately() inList.Name.Should().Be("Banana Split"); } + [Fact] + public void Update_ToExplicitList_DoesNotLeakIntoInternalStoreOnNextBareSaveChanges() + { + // Update(entity, externalList) applies immediately to externalList — it must NOT also + // queue the change for replay against the internal store on a later bare SaveChanges(). + var seed = CreateMutableSeed(); + var evaluator = CreateEvaluator(seed); // internal store is a separate copy, also containing Id=2 + var externalList = CreateMutableSeed(); // unrelated external list, happens to share the same IDs + var updated = new TestProduct { Id = 2, Name = "Banana Split", Category = "Fruit", Price = 0.9m, Stock = 155, IsActive = true }; + + evaluator.Update(updated, externalList); + evaluator.SaveChanges(); // targets the internal store, unrelated to externalList + + TestProduct? internalEntry = evaluator.GetFirst(null, new ValiFlow().EqualTo(p => p.Id, 2)); + internalEntry!.Name.Should().Be("Banana", "the update was only meant for externalList, not the internal store"); + } + // ----------------------------------------------------------------------- // UpdateRange // ----------------------------------------------------------------------- diff --git a/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Bridge.cs b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Bridge.cs new file mode 100644 index 0000000..35bf0f5 --- /dev/null +++ b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Bridge.cs @@ -0,0 +1,37 @@ +using System.Linq.Expressions; +using Vali_Flow.Abstractions.Interfaces; +using Vali_Flow.Core.Builder; + +namespace Vali_Flow.InMemory.Classes.Evaluators; + +/// Explicit / implementation — provider-agnostic async surface, delegated to . +public partial class ValiFlowEvaluator +{ + Task IQueryReader.EvaluateAnyAsync(ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateAnyAsync(filter, cancellationToken); + + Task IQueryReader.EvaluateCountAsync(ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateCountAsync(filter, cancellationToken); + + Task IQueryReader.EvaluateGetFirstAsync(ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateGetFirstAsync(filter, cancellationToken); + + Task IQueryReader.EvaluateGetLastAsync(ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateGetLastAsync(filter, cancellationToken); + + Task IQueryAggregator.EvaluateMinAsync( + Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateMinAsync(selector, filter, cancellationToken); + + Task IQueryAggregator.EvaluateMaxAsync( + Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateMaxAsync(selector, filter, cancellationToken); + + Task IQueryAggregator.EvaluateAverageAsync( + Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateAverageAsync(selector, filter, cancellationToken); + + Task IQueryAggregator.EvaluateSumAsync( + Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) + => AsyncAdapter.EvaluateSumAsync(selector, filter, cancellationToken); +} diff --git a/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Grouped.cs b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Grouped.cs new file mode 100644 index 0000000..bf855f7 --- /dev/null +++ b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Grouped.cs @@ -0,0 +1,326 @@ +using System.Numerics; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.Core.Builder; + +namespace Vali_Flow.InMemory.Classes.Evaluators; + +public partial class ValiFlowEvaluator +{ + /// + /// Groups matching entities by a key selector and returns a dictionary of lists. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to group entities. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary mapping each key to its group of entities. + public Dictionary> EvaluateGrouped( + IEnumerable? entities, + Func keySelector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateGrouped", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + Func condition = GetDefaultCondition(valiFlow, negateCondition); + var result = new Dictionary>(); + foreach (T item in dataSource) + { + if (!condition(item)) continue; + TKey key = keySelector(item); + if (!result.TryGetValue(key, out List? group)) + result[key] = group = new List(); + group.Add(item); + } + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the count of matching entities per group key. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to group entities. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary mapping each key to its entity count. + public Dictionary EvaluateCountByGroup( + IEnumerable? entities, + Func keySelector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateCountByGroup", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(keySelector) + .ToDictionary(g => g.Key, g => g.Count()); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the sum of a numeric property per group key for all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to group entities. + /// Property selector for the numeric value to sum. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary mapping each key to the sum of the selected property. + public Dictionary EvaluateSumByGroup( + IEnumerable? entities, + Func keySelector, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateSumByGroup", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(keySelector) + .ToDictionary(g => g.Key, g => + g.Aggregate(TResult.Zero, (acc, item) => acc + selector(item))); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the minimum value of a numeric property per group key for all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to group entities. + /// Property selector for the numeric value to minimize. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary mapping each key to the minimum of the selected property, or TResult.Zero for empty groups. + public Dictionary EvaluateMinByGroup( + IEnumerable? entities, + Func keySelector, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateMinByGroup", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(keySelector) + .ToDictionary(g => g.Key, g => g.Select(selector).Min() ?? TResult.Zero); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the maximum value of a numeric property per group key for all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to group entities. + /// Property selector for the numeric value to maximize. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary mapping each key to the maximum of the selected property, or TResult.Zero for empty groups. + public Dictionary EvaluateMaxByGroup( + IEnumerable? entities, + Func keySelector, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateMaxByGroup", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(keySelector) + .ToDictionary(g => g.Key, g => g.Select(selector).Max() ?? TResult.Zero); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the average of a numeric property per group key for all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to group entities. + /// Property selector for the numeric value to average. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary mapping each key to the average of the selected property. + public Dictionary EvaluateAverageByGroup( + IEnumerable? entities, + Func keySelector, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateAverageByGroup", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + Func condition = GetDefaultCondition(valiFlow, negateCondition); + return dataSource.Where(condition) + .GroupBy(keySelector) + .ToDictionary(g => g.Key, g => ComputeAverage(g.Select(selector))); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns groups where the key appears more than once among matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to detect duplicates. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary containing only groups with more than one element. + public Dictionary> EvaluateDuplicatesByGroup( + IEnumerable? entities, + Func keySelector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateDuplicatesByGroup", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(keySelector) + .Where(g => g.Skip(1).Any()) + .ToDictionary(g => g.Key, g => g.ToList()); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns groups where the key appears exactly once among matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to identify unique groups. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary containing only singleton groups, mapping each key to its single entity. + public Dictionary EvaluateUniquesByGroup( + IEnumerable? entities, + Func keySelector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateUniquesByGroup", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(keySelector) + .Where(g => !g.Skip(1).Any()) + .ToDictionary(g => g.Key, g => g.First()); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the top entities per group key, with optional ordering within each group. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to group entities. + /// Maximum number of entities to include per group. + /// Optional ordering key applied before grouping. + /// When , orders ascending; otherwise descending. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Dictionary mapping each key to its top entities. + /// Thrown when is less than or equal to zero. + public Dictionary> EvaluateTopByGroup( + IEnumerable? entities, + Func keySelector, + int count, + Func? orderBy = null, + bool ascending = true, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TKey : notnull + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateTopByGroup", tag, typeof(T).Name); + try + { + if (count <= 0) throw new ArgumentOutOfRangeException(nameof(count), "Count must be greater than zero."); + IEnumerable dataSource = entities ?? _store.Items; + IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)); + if (orderBy != null) query = ascending ? query.OrderBy(orderBy) : query.OrderByDescending(orderBy); + + return query.GroupBy(keySelector) + .ToDictionary(g => g.Key, g => g.Take(count).ToList()); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } +} diff --git a/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Read.cs b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Read.cs new file mode 100644 index 0000000..5d3a3e5 --- /dev/null +++ b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Read.cs @@ -0,0 +1,655 @@ +using System.Numerics; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.Core.Builder; +using Vali_Flow.InMemory.Classes.Options; +using Vali_Flow.InMemory.Models; + +namespace Vali_Flow.InMemory.Classes.Evaluators; + +public partial class ValiFlowEvaluator +{ + /// + /// Evaluates whether a single entity satisfies the active filter. + /// + /// The entity to evaluate. + /// Optional filter override; uses the instance default when . + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// if the entity matches the (possibly negated) condition. + public bool Evaluate(T entity, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.Evaluate", tag, typeof(T).Name); + try + { + return GetDefaultCondition(valiFlow, negateCondition)(entity); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Determines whether any entity in the collection satisfies the filter. + /// + /// Source collection; falls back to the internal store when . + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// if at least one entity matches. + public bool EvaluateAny(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateAny", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Any(GetDefaultCondition(valiFlow, negateCondition)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the count of entities that satisfy the filter. + /// + /// Source collection; falls back to the internal store when . + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Number of matching entities. + public int EvaluateCount(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateCount", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Count(GetDefaultCondition(valiFlow, negateCondition)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the first entity that does NOT satisfy the filter. + /// + /// Source collection; falls back to the internal store when . + /// Optional filter override. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// The first non-matching entity, or if none exists. + public T? GetFirstFailed(IEnumerable? entities = null, ValiFlow? valiFlow = null, string? tag = null) + => GetFirst(entities, valiFlow, negateCondition: true, tag: tag); + + /// + /// Returns the first entity that satisfies the filter. + /// + /// Source collection; falls back to the internal store when . + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// The first matching entity, or if none exists. + public T? GetFirst(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.GetFirst", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.FirstOrDefault(GetDefaultCondition(valiFlow, negateCondition)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns all entities that do NOT satisfy the filter, with optional ordering. + /// + /// Source collection; falls back to the internal store when . + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// Ordered sequence of non-matching entities. + public IEnumerable EvaluateAllFailed( + IEnumerable? entities = null, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateAllFailed", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negated: true)); + return ApplyOrdering(query, orderBy, ascending, thenBys); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns all entities that satisfy the filter, with optional ordering. + /// + /// Source collection; falls back to the internal store when . + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Ordered sequence of matching entities. + public IEnumerable EvaluateAll( + IEnumerable? entities = null, Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateAll", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)); + return ApplyOrdering(query, orderBy, ascending, thenBys); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns a paged subset of entities that satisfy the filter. + /// + /// Source collection; falls back to the internal store when . + /// 1-based page number. + /// Number of items per page. + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Sequence of entities for the requested page. + /// Thrown when or is less than 1. + public IEnumerable EvaluatePaged( + IEnumerable? entities = null, + int page = 1, + int pageSize = 10, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluatePaged", tag, typeof(T).Name); + try + { + if (page < 1) throw new ArgumentOutOfRangeException(nameof(page), "Page must be greater than or equal to 1."); + if (pageSize < 1) throw new ArgumentOutOfRangeException(nameof(pageSize), "Page size must be greater than or equal to 1."); + IEnumerable dataSource = entities ?? _store.Items; + IEnumerable query = EvaluateAll(dataSource, orderBy, ascending, thenBys, valiFlow, negateCondition); + return query.Skip((page - 1) * pageSize).Take(pageSize); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns a containing the paged data and total count. + /// + /// Source collection; falls back to the internal store when . + /// 1-based page number. + /// Number of items per page. + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// A with the current page items and the total filtered count. + /// Thrown when or is less than 1. + public PagedResult EvaluatePagedResult( + IEnumerable? entities = null, + int page = 1, + int pageSize = 10, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluatePagedResult", tag, typeof(T).Name); + try + { + if (page < 1) throw new ArgumentOutOfRangeException(nameof(page), "Page must be greater than or equal to 1."); + if (pageSize < 1) throw new ArgumentOutOfRangeException(nameof(pageSize), "Page size must be greater than or equal to 1."); + IEnumerable dataSource = entities ?? _store.Items; + var filtered = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)).ToList(); + int totalCount = filtered.Count; + IEnumerable ordered = ApplyOrdering(filtered, orderBy, ascending, thenBys); + List pageItems = ordered.Skip((page - 1) * pageSize).Take(pageSize).ToList(); + return new PagedResult(pageItems, totalCount, page, pageSize); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the top entities that satisfy the filter. + /// + /// Source collection; falls back to the internal store when . + /// Maximum number of entities to return. + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Sequence of up to matching entities. + /// Thrown when is less than or equal to zero. + public IEnumerable EvaluateTop( + IEnumerable? entities = null, + int count = 10, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateTop", tag, typeof(T).Name); + try + { + if (count <= 0) throw new ArgumentOutOfRangeException(nameof(count), "Count must be greater than zero."); + IEnumerable dataSource = entities ?? _store.Items; + IEnumerable query = EvaluateAll(dataSource, orderBy, ascending, thenBys, valiFlow, negateCondition); + return query.Take(count); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns distinct entities based on a key selector, with optional ordering. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to determine uniqueness. + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Sequence of distinct matching entities. + /// Thrown when is . + public IEnumerable EvaluateDistinct( + IEnumerable? entities, + Func selector, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateDistinct", tag, typeof(T).Name); + try + { + if (selector == null) throw new ArgumentNullException(nameof(selector)); + IEnumerable dataSource = entities ?? _store.Items; + IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(selector) + .Select(g => g.First()); + + return ApplyOrdering(query, orderBy, ascending, thenBys); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns all entities whose key appears more than once in the filtered collection. + /// + /// Source collection; falls back to the internal store when . + /// Key selector used to detect duplicates. + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// All entities belonging to duplicate groups. + /// Thrown when is . + public IEnumerable EvaluateDuplicates( + IEnumerable? entities, + Func selector, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateDuplicates", tag, typeof(T).Name); + try + { + if (selector == null) throw new ArgumentNullException(nameof(selector)); + IEnumerable dataSource = entities ?? _store.Items; + IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) + .GroupBy(selector) + .Where(g => g.Count() > 1) + .SelectMany(g => g); + + return ApplyOrdering(query, orderBy, ascending, thenBys); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the zero-based index of the first entity that satisfies the filter after ordering. + /// + /// Source collection; falls back to the internal store when . + /// Primary key selector for ordering before index lookup. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Zero-based index of the first match, or -1 if not found. + public int GetFirstMatchIndex( + IEnumerable? entities = null, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.GetFirstMatchIndex", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + List ordered = ApplyOrdering(dataSource, orderBy, ascending, thenBys).ToList(); + Func condition = GetDefaultCondition(valiFlow, negateCondition); + return ordered.FindIndex(item => condition(item)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the zero-based index of the last entity that satisfies the filter after ordering. + /// + /// Source collection; falls back to the internal store when . + /// Primary key selector for ordering before index lookup. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Zero-based index of the last match, or -1 if not found. + public int GetLastMatchIndex( + IEnumerable? entities = null, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.GetLastMatchIndex", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + List ordered = ApplyOrdering(dataSource, orderBy, ascending, thenBys).ToList(); + Func condition = GetDefaultCondition(valiFlow, negateCondition); + return ordered.FindLastIndex(item => condition(item)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the last entity that does NOT satisfy the filter. + /// + /// Source collection; falls back to the internal store when . + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// The last non-matching entity, or if none exists. + public T? GetLastFailed( + IEnumerable? entities = null, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + string? tag = null + ) => GetLast(entities, orderBy, ascending, thenBys, valiFlow, negateCondition: true, tag: tag); + + /// + /// Returns the last entity that satisfies the filter. + /// + /// Source collection; falls back to the internal store when . + /// Primary key selector for ordering. + /// When , orders ascending; otherwise descending. + /// Optional secondary sort criteria. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// The last matching entity, or if none exists. + public T? GetLast( + IEnumerable? entities = null, + Func? orderBy = null, + bool ascending = true, + IEnumerable>? thenBys = null, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.GetLast", tag, typeof(T).Name); + try + { + return EvaluateAll(entities, orderBy, ascending, thenBys, valiFlow, negateCondition).LastOrDefault(); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the minimum value of a numeric property across all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Property selector for the numeric value. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Minimum value, or TResult.Zero when no entities match. + public TResult EvaluateMin( + IEnumerable? entities, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateMin", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)).Select(selector).Min() ?? TResult.Zero; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the maximum value of a numeric property across all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Property selector for the numeric value. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Maximum value, or TResult.Zero when no entities match. + public TResult EvaluateMax( + IEnumerable? entities, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateMax", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)).Select(selector).Max() ?? TResult.Zero; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the average value of a numeric property across all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Property selector for the numeric value. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Average as , or 0 when no entities match. + public decimal EvaluateAverage( + IEnumerable? entities, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateAverage", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + Func condition = GetDefaultCondition(valiFlow, negateCondition); + return ComputeAverage(dataSource.Where(condition).Select(selector)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Returns the sum of a numeric property across all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Property selector for the numeric value. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Sum of the selected values, or TResult.Zero when no entities match. + public TResult EvaluateSum( + IEnumerable? entities, + Func selector, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateSum", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource + .Where(GetDefaultCondition(valiFlow, negateCondition)) + .Aggregate(TResult.Zero, (acc, item) => acc + selector(item)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Applies a custom aggregation function over a numeric property of all matching entities. + /// + /// Source collection; falls back to the internal store when . + /// Property selector for the numeric value. + /// Binary accumulator function applied to successive values. + /// Optional filter override. + /// When , the filter predicate is logically negated. + /// Aggregated result, starting from TResult.Zero. + public TResult EvaluateAggregate( + IEnumerable? entities, + Func selector, + Func aggregator, + ValiFlow? valiFlow = null, + bool negateCondition = false, + string? tag = null + ) where TResult : INumber + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.EvaluateAggregate", tag, typeof(T).Name); + try + { + IEnumerable dataSource = entities ?? _store.Items; + return dataSource + .Where(GetDefaultCondition(valiFlow, negateCondition)) + .Select(selector) + .Aggregate(TResult.Zero, aggregator); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + +} diff --git a/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Write.cs b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Write.cs new file mode 100644 index 0000000..acb9406 --- /dev/null +++ b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.Write.cs @@ -0,0 +1,193 @@ +using Vali_Flow.Abstractions.Diagnostics; + +namespace Vali_Flow.InMemory.Classes.Evaluators; + +public partial class ValiFlowEvaluator +{ + /// Adds a single entity to the store or the supplied list. + /// Entity to add. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// if the entity was added successfully. + public bool Add(T entity, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.Add", tag, typeof(T).Name); + try + { + return _store.Add(entity, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Updates a matching entity in the store or the supplied list. + /// Entity with updated values; matched by the configured key selector. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// The updated entity, or if no matching entity was found. + public T? Update(T entity, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.Update", tag, typeof(T).Name); + try + { + return _store.Update(entity, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Removes a matching entity from the store or the supplied list. + /// Entity to remove; matched by the configured key selector. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// if the entity was found and removed. + public bool Delete(T entity, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.Delete", tag, typeof(T).Name); + try + { + return _store.Delete(entity, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Adds multiple entities to the store or the supplied list. + /// Entities to add. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + public void AddRange(IEnumerable entitiesToAdd, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.AddRange", tag, typeof(T).Name); + try + { + _store.AddRange(entitiesToAdd, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Updates multiple matching entities in the store or the supplied list. + /// Entities with updated values; each matched by the configured key selector. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Sequence of successfully updated entities. + public IEnumerable UpdateRange(IEnumerable entitiesToUpdate, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.UpdateRange", tag, typeof(T).Name); + try + { + return _store.UpdateRange(entitiesToUpdate, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Removes multiple matching entities from the store or the supplied list. + /// Entities to remove; each matched by the configured key selector. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Number of entities removed. + public int DeleteRange(IEnumerable entitiesToDelete, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.DeleteRange", tag, typeof(T).Name); + try + { + return _store.DeleteRange(entitiesToDelete, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Inserts or updates a single entity in the store or the supplied list. + /// Entity to insert if not found, or update if already present (matched by key selector). + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// The inserted or updated entity. + public T Upsert(T entity, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.Upsert", tag, typeof(T).Name); + try + { + return _store.Upsert(entity, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Inserts or updates multiple entities in the store or the supplied list. + /// Entities to insert or update; each matched by the configured key selector. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Sequence of inserted or updated entities. + public IEnumerable UpsertRange(IEnumerable entitiesToUpsert, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.UpsertRange", tag, typeof(T).Name); + try + { + return _store.UpsertRange(entitiesToUpsert, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Removes all entities that satisfy an arbitrary predicate. + /// Condition an entity must meet to be removed. + /// Optional external list to operate on instead of the internal store. + /// Optional diagnostics tag identifying why/where this operation was triggered. + /// Number of entities removed. + public int DeleteByCondition(Func predicate, List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.DeleteByCondition", tag, typeof(T).Name); + try + { + return _store.DeleteByCondition(predicate, entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// Persists pending changes to the internal store or flushes the supplied list. + /// Optional external list whose changes should be committed. + /// Optional diagnostics tag identifying why/where this operation was triggered. + public void SaveChanges(List? entities = null, string? tag = null) + { + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.InMemory.SaveChanges", tag, typeof(T).Name); + try + { + _store.SaveChanges(entities); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } +} diff --git a/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.cs b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.cs index d78a5e7..62f9d7a 100644 --- a/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.cs +++ b/Vali-Flow.InMemory/Classes/Evaluators/ValiFlowEvaluator.cs @@ -1,4 +1,3 @@ -using System.Linq.Expressions; using System.Numerics; using Vali_Flow.Abstractions.Interfaces; using Vali_Flow.Core.Builder; @@ -6,7 +5,6 @@ using Vali_Flow.InMemory.Classes.Stores; using Vali_Flow.InMemory.Interfaces.Evaluators.Read; using Vali_Flow.InMemory.Interfaces.Evaluators.Write; -using Vali_Flow.InMemory.Models; namespace Vali_Flow.InMemory.Classes.Evaluators; @@ -16,7 +14,7 @@ namespace Vali_Flow.InMemory.Classes.Evaluators; /// /// The type of the entities to evaluate. Must be a reference type. /// The type of the property used as the entity identifier key. Must be non-nullable. -public class ValiFlowEvaluator : IInMemoryEvaluatorRead, IInMemoryEvaluatorWrite +public partial class ValiFlowEvaluator : IInMemoryEvaluatorRead, IInMemoryEvaluatorWrite where T : class where TProperty : notnull { @@ -80,677 +78,6 @@ private Func GetDefaultCondition(ValiFlow? valiFlow = null, bool neg } } - /// - /// Evaluates whether a single entity satisfies the active filter. - /// - /// The entity to evaluate. - /// Optional filter override; uses the instance default when . - /// When , the filter predicate is logically negated. - /// if the entity matches the (possibly negated) condition. - public bool Evaluate(T entity, ValiFlow? valiFlow = null, bool negateCondition = false) - { - return GetDefaultCondition(valiFlow, negateCondition)(entity); - } - - /// - /// Determines whether any entity in the collection satisfies the filter. - /// - /// Source collection; falls back to the internal store when . - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// if at least one entity matches. - public bool EvaluateAny(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false) - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Any(GetDefaultCondition(valiFlow, negateCondition)); - } - - /// - /// Returns the count of entities that satisfy the filter. - /// - /// Source collection; falls back to the internal store when . - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Number of matching entities. - public int EvaluateCount(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false) - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Count(GetDefaultCondition(valiFlow, negateCondition)); - } - - /// - /// Returns the first entity that does NOT satisfy the filter. - /// - /// Source collection; falls back to the internal store when . - /// Optional filter override. - /// The first non-matching entity, or if none exists. - public T? GetFirstFailed(IEnumerable? entities = null, ValiFlow? valiFlow = null) - => GetFirst(entities, valiFlow, negateCondition: true); - - /// - /// Returns the first entity that satisfies the filter. - /// - /// Source collection; falls back to the internal store when . - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// The first matching entity, or if none exists. - public T? GetFirst(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false) - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.FirstOrDefault(GetDefaultCondition(valiFlow, negateCondition)); - } - - /// - /// Returns all entities that do NOT satisfy the filter, with optional ordering. - /// - /// Source collection; falls back to the internal store when . - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// Ordered sequence of non-matching entities. - public IEnumerable EvaluateAllFailed( - IEnumerable? entities = null, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null - ) - { - IEnumerable dataSource = entities ?? _store.Items; - IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negated: true)); - return ApplyOrdering(query, orderBy, ascending, thenBys); - } - - /// - /// Returns all entities that satisfy the filter, with optional ordering. - /// - /// Source collection; falls back to the internal store when . - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Ordered sequence of matching entities. - public IEnumerable EvaluateAll( - IEnumerable? entities = null, Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - IEnumerable dataSource = entities ?? _store.Items; - IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)); - return ApplyOrdering(query, orderBy, ascending, thenBys); - } - - /// - /// Returns a paged subset of entities that satisfy the filter. - /// - /// Source collection; falls back to the internal store when . - /// 1-based page number. - /// Number of items per page. - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Sequence of entities for the requested page. - /// Thrown when or is less than 1. - public IEnumerable EvaluatePaged( - IEnumerable? entities = null, - int page = 1, - int pageSize = 10, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, bool negateCondition = false - ) - { - if (page < 1) throw new ArgumentOutOfRangeException(nameof(page), "Page must be greater than or equal to 1."); - if (pageSize < 1) throw new ArgumentOutOfRangeException(nameof(pageSize), "Page size must be greater than or equal to 1."); - IEnumerable dataSource = entities ?? _store.Items; - IEnumerable query = EvaluateAll(dataSource, orderBy, ascending, thenBys, valiFlow, negateCondition); - return query.Skip((page - 1) * pageSize).Take(pageSize); - } - - /// - /// Returns a containing the paged data and total count. - /// - /// Source collection; falls back to the internal store when . - /// 1-based page number. - /// Number of items per page. - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// A with the current page items and the total filtered count. - /// Thrown when or is less than 1. - public PagedResult EvaluatePagedResult( - IEnumerable? entities = null, - int page = 1, - int pageSize = 10, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - if (page < 1) throw new ArgumentOutOfRangeException(nameof(page), "Page must be greater than or equal to 1."); - if (pageSize < 1) throw new ArgumentOutOfRangeException(nameof(pageSize), "Page size must be greater than or equal to 1."); - IEnumerable dataSource = entities ?? _store.Items; - var filtered = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)).ToList(); - int totalCount = filtered.Count; - IEnumerable ordered = ApplyOrdering(filtered, orderBy, ascending, thenBys); - List pageItems = ordered.Skip((page - 1) * pageSize).Take(pageSize).ToList(); - return new PagedResult(pageItems, totalCount, page, pageSize); - } - - /// - /// Returns the top entities that satisfy the filter. - /// - /// Source collection; falls back to the internal store when . - /// Maximum number of entities to return. - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Sequence of up to matching entities. - /// Thrown when is less than or equal to zero. - public IEnumerable EvaluateTop( - IEnumerable? entities = null, - int count = 10, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - if (count <= 0) throw new ArgumentOutOfRangeException(nameof(count), "Count must be greater than zero."); - IEnumerable dataSource = entities ?? _store.Items; - IEnumerable query = EvaluateAll(dataSource, orderBy, ascending, thenBys, valiFlow, negateCondition); - return query.Take(count); - } - - /// - /// Returns distinct entities based on a key selector, with optional ordering. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to determine uniqueness. - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Sequence of distinct matching entities. - /// Thrown when is . - public IEnumerable EvaluateDistinct( - IEnumerable? entities, - Func selector, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - if (selector == null) throw new ArgumentNullException(nameof(selector)); - IEnumerable dataSource = entities ?? _store.Items; - IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(selector) - .Select(g => g.First()); - - return ApplyOrdering(query, orderBy, ascending, thenBys); - } - - /// - /// Returns all entities whose key appears more than once in the filtered collection. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to detect duplicates. - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// All entities belonging to duplicate groups. - /// Thrown when is . - public IEnumerable EvaluateDuplicates( - IEnumerable? entities, - Func selector, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - if (selector == null) throw new ArgumentNullException(nameof(selector)); - IEnumerable dataSource = entities ?? _store.Items; - IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(selector) - .Where(g => g.Count() > 1) - .SelectMany(g => g); - - return ApplyOrdering(query, orderBy, ascending, thenBys); - } - - /// - /// Returns the zero-based index of the first entity that satisfies the filter after ordering. - /// - /// Source collection; falls back to the internal store when . - /// Primary key selector for ordering before index lookup. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Zero-based index of the first match, or -1 if not found. - public int GetFirstMatchIndex( - IEnumerable? entities = null, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - IEnumerable dataSource = entities ?? _store.Items; - List ordered = ApplyOrdering(dataSource, orderBy, ascending, thenBys).ToList(); - Func condition = GetDefaultCondition(valiFlow, negateCondition); - return ordered.FindIndex(item => condition(item)); - } - - /// - /// Returns the zero-based index of the last entity that satisfies the filter after ordering. - /// - /// Source collection; falls back to the internal store when . - /// Primary key selector for ordering before index lookup. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Zero-based index of the last match, or -1 if not found. - public int GetLastMatchIndex( - IEnumerable? entities = null, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - IEnumerable dataSource = entities ?? _store.Items; - List ordered = ApplyOrdering(dataSource, orderBy, ascending, thenBys).ToList(); - Func condition = GetDefaultCondition(valiFlow, negateCondition); - return ordered.FindLastIndex(item => condition(item)); - } - - /// - /// Returns the last entity that does NOT satisfy the filter. - /// - /// Source collection; falls back to the internal store when . - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// The last non-matching entity, or if none exists. - public T? GetLastFailed( - IEnumerable? entities = null, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null - ) => GetLast(entities, orderBy, ascending, thenBys, valiFlow, negateCondition: true); - - /// - /// Returns the last entity that satisfies the filter. - /// - /// Source collection; falls back to the internal store when . - /// Primary key selector for ordering. - /// When , orders ascending; otherwise descending. - /// Optional secondary sort criteria. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// The last matching entity, or if none exists. - public T? GetLast( - IEnumerable? entities = null, - Func? orderBy = null, - bool ascending = true, - IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) - { - return EvaluateAll(entities, orderBy, ascending, thenBys, valiFlow, negateCondition).LastOrDefault(); - } - - /// - /// Returns the minimum value of a numeric property across all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Property selector for the numeric value. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Minimum value, or TResult.Zero when no entities match. - public TResult EvaluateMin( - IEnumerable? entities, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)).Select(selector).Min() ?? TResult.Zero; - } - - /// - /// Returns the maximum value of a numeric property across all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Property selector for the numeric value. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Maximum value, or TResult.Zero when no entities match. - public TResult EvaluateMax( - IEnumerable? entities, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)).Select(selector).Max() ?? TResult.Zero; - } - - /// - /// Returns the average value of a numeric property across all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Property selector for the numeric value. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Average as , or 0 when no entities match. - public decimal EvaluateAverage( - IEnumerable? entities, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - Func condition = GetDefaultCondition(valiFlow, negateCondition); - return ComputeAverage(dataSource.Where(condition).Select(selector)); - } - - /// - /// Returns the sum of a numeric property across all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Property selector for the numeric value. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Sum of the selected values, or TResult.Zero when no entities match. - public TResult EvaluateSum( - IEnumerable? entities, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource - .Where(GetDefaultCondition(valiFlow, negateCondition)) - .Aggregate(TResult.Zero, (acc, item) => acc + selector(item)); - } - - /// - /// Applies a custom aggregation function over a numeric property of all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Property selector for the numeric value. - /// Binary accumulator function applied to successive values. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Aggregated result, starting from TResult.Zero. - public TResult EvaluateAggregate( - IEnumerable? entities, - Func selector, - Func aggregator, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource - .Where(GetDefaultCondition(valiFlow, negateCondition)) - .Select(selector) - .Aggregate(TResult.Zero, aggregator); - } - - /// - /// Groups matching entities by a key selector and returns a dictionary of lists. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to group entities. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary mapping each key to its group of entities. - public Dictionary> EvaluateGrouped( - IEnumerable? entities, - Func keySelector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull - { - IEnumerable dataSource = entities ?? _store.Items; - Func condition = GetDefaultCondition(valiFlow, negateCondition); - var result = new Dictionary>(); - foreach (T item in dataSource) - { - if (!condition(item)) continue; - TKey key = keySelector(item); - if (!result.TryGetValue(key, out List? group)) - result[key] = group = new List(); - group.Add(item); - } - return result; - } - - /// - /// Returns the count of matching entities per group key. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to group entities. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary mapping each key to its entity count. - public Dictionary EvaluateCountByGroup( - IEnumerable? entities, - Func keySelector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(keySelector) - .ToDictionary(g => g.Key, g => g.Count()); - } - - /// - /// Returns the sum of a numeric property per group key for all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to group entities. - /// Property selector for the numeric value to sum. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary mapping each key to the sum of the selected property. - public Dictionary EvaluateSumByGroup( - IEnumerable? entities, - Func keySelector, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(keySelector) - .ToDictionary(g => g.Key, g => - g.Aggregate(TResult.Zero, (acc, item) => acc + selector(item))); - } - - /// - /// Returns the minimum value of a numeric property per group key for all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to group entities. - /// Property selector for the numeric value to minimize. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary mapping each key to the minimum of the selected property, or TResult.Zero for empty groups. - public Dictionary EvaluateMinByGroup( - IEnumerable? entities, - Func keySelector, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(keySelector) - .ToDictionary(g => g.Key, g => g.Select(selector).Min() ?? TResult.Zero); - } - - /// - /// Returns the maximum value of a numeric property per group key for all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to group entities. - /// Property selector for the numeric value to maximize. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary mapping each key to the maximum of the selected property, or TResult.Zero for empty groups. - public Dictionary EvaluateMaxByGroup( - IEnumerable? entities, - Func keySelector, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(keySelector) - .ToDictionary(g => g.Key, g => g.Select(selector).Max() ?? TResult.Zero); - } - - /// - /// Returns the average of a numeric property per group key for all matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to group entities. - /// Property selector for the numeric value to average. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary mapping each key to the average of the selected property. - public Dictionary EvaluateAverageByGroup( - IEnumerable? entities, - Func keySelector, - Func selector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull where TResult : INumber - { - IEnumerable dataSource = entities ?? _store.Items; - Func condition = GetDefaultCondition(valiFlow, negateCondition); - return dataSource.Where(condition) - .GroupBy(keySelector) - .ToDictionary(g => g.Key, g => ComputeAverage(g.Select(selector))); - } - - /// - /// Returns groups where the key appears more than once among matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to detect duplicates. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary containing only groups with more than one element. - public Dictionary> EvaluateDuplicatesByGroup( - IEnumerable? entities, - Func keySelector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(keySelector) - .Where(g => g.Skip(1).Any()) - .ToDictionary(g => g.Key, g => g.ToList()); - } - - /// - /// Returns groups where the key appears exactly once among matching entities. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to identify unique groups. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary containing only singleton groups, mapping each key to its single entity. - public Dictionary EvaluateUniquesByGroup( - IEnumerable? entities, - Func keySelector, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull - { - IEnumerable dataSource = entities ?? _store.Items; - return dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)) - .GroupBy(keySelector) - .Where(g => !g.Skip(1).Any()) - .ToDictionary(g => g.Key, g => g.First()); - } - - /// - /// Returns the top entities per group key, with optional ordering within each group. - /// - /// Source collection; falls back to the internal store when . - /// Key selector used to group entities. - /// Maximum number of entities to include per group. - /// Optional ordering key applied before grouping. - /// When , orders ascending; otherwise descending. - /// Optional filter override. - /// When , the filter predicate is logically negated. - /// Dictionary mapping each key to its top entities. - /// Thrown when is less than or equal to zero. - public Dictionary> EvaluateTopByGroup( - IEnumerable? entities, - Func keySelector, - int count, - Func? orderBy = null, - bool ascending = true, - ValiFlow? valiFlow = null, - bool negateCondition = false - ) where TKey : notnull - { - if (count <= 0) throw new ArgumentOutOfRangeException(nameof(count), "Count must be greater than zero."); - IEnumerable dataSource = entities ?? _store.Items; - IEnumerable query = dataSource.Where(GetDefaultCondition(valiFlow, negateCondition)); - if (orderBy != null) query = ascending ? query.OrderBy(orderBy) : query.OrderByDescending(orderBy); - - return query.GroupBy(keySelector) - .ToDictionary(g => g.Key, g => g.Take(count).ToList()); - } - #endregion #region Methods Private @@ -803,102 +130,4 @@ private IEnumerable ApplyOrdering( } #endregion - - #region Methods Write - - /// Adds a single entity to the store or the supplied list. - /// Entity to add. - /// Optional external list to operate on instead of the internal store. - /// if the entity was added successfully. - public bool Add(T entity, List? entities = null) => _store.Add(entity, entities); - - /// Updates a matching entity in the store or the supplied list. - /// Entity with updated values; matched by the configured key selector. - /// Optional external list to operate on instead of the internal store. - /// The updated entity, or if no matching entity was found. - public T? Update(T entity, List? entities = null) => _store.Update(entity, entities); - - /// Removes a matching entity from the store or the supplied list. - /// Entity to remove; matched by the configured key selector. - /// Optional external list to operate on instead of the internal store. - /// if the entity was found and removed. - public bool Delete(T entity, List? entities = null) => _store.Delete(entity, entities); - - /// Adds multiple entities to the store or the supplied list. - /// Entities to add. - /// Optional external list to operate on instead of the internal store. - public void AddRange(IEnumerable entitiesToAdd, List? entities = null) => - _store.AddRange(entitiesToAdd, entities); - - /// Updates multiple matching entities in the store or the supplied list. - /// Entities with updated values; each matched by the configured key selector. - /// Optional external list to operate on instead of the internal store. - /// Sequence of successfully updated entities. - public IEnumerable UpdateRange(IEnumerable entitiesToUpdate, List? entities = null) => - _store.UpdateRange(entitiesToUpdate, entities); - - /// Removes multiple matching entities from the store or the supplied list. - /// Entities to remove; each matched by the configured key selector. - /// Optional external list to operate on instead of the internal store. - /// Number of entities removed. - public int DeleteRange(IEnumerable entitiesToDelete, List? entities = null) => - _store.DeleteRange(entitiesToDelete, entities); - - /// Inserts or updates a single entity in the store or the supplied list. - /// Entity to insert if not found, or update if already present (matched by key selector). - /// Optional external list to operate on instead of the internal store. - /// The inserted or updated entity. - public T Upsert(T entity, List? entities = null) => _store.Upsert(entity, entities); - - /// Inserts or updates multiple entities in the store or the supplied list. - /// Entities to insert or update; each matched by the configured key selector. - /// Optional external list to operate on instead of the internal store. - /// Sequence of inserted or updated entities. - public IEnumerable UpsertRange(IEnumerable entitiesToUpsert, List? entities = null) => - _store.UpsertRange(entitiesToUpsert, entities); - - /// Removes all entities that satisfy an arbitrary predicate. - /// Condition an entity must meet to be removed. - /// Optional external list to operate on instead of the internal store. - /// Number of entities removed. - public int DeleteByCondition(Func predicate, List? entities = null) => - _store.DeleteByCondition(predicate, entities); - - /// Persists pending changes to the internal store or flushes the supplied list. - /// Optional external list whose changes should be committed. - public void SaveChanges(List? entities = null) => _store.SaveChanges(entities); - - #endregion - - #region IQueryReader + IQueryAggregator — provider-agnostic methods - - Task IQueryReader.EvaluateAnyAsync(ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateAnyAsync(filter, cancellationToken); - - Task IQueryReader.EvaluateCountAsync(ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateCountAsync(filter, cancellationToken); - - Task IQueryReader.EvaluateGetFirstAsync(ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateGetFirstAsync(filter, cancellationToken); - - Task IQueryReader.EvaluateGetLastAsync(ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateGetLastAsync(filter, cancellationToken); - - Task IQueryAggregator.EvaluateMinAsync( - Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateMinAsync(selector, filter, cancellationToken); - - Task IQueryAggregator.EvaluateMaxAsync( - Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateMaxAsync(selector, filter, cancellationToken); - - Task IQueryAggregator.EvaluateAverageAsync( - Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateAverageAsync(selector, filter, cancellationToken); - - Task IQueryAggregator.EvaluateSumAsync( - Expression> selector, ValiFlow? filter, CancellationToken cancellationToken) - => AsyncAdapter.EvaluateSumAsync(selector, filter, cancellationToken); - - #endregion } diff --git a/Vali-Flow.InMemory/Classes/Stores/InMemoryWriteStore.cs b/Vali-Flow.InMemory/Classes/Stores/InMemoryWriteStore.cs index 9daa7b2..ae8b8b6 100644 --- a/Vali-Flow.InMemory/Classes/Stores/InMemoryWriteStore.cs +++ b/Vali-Flow.InMemory/Classes/Stores/InMemoryWriteStore.cs @@ -63,13 +63,19 @@ internal bool Add(T entity, List? entities = null) dataSource.FirstOrDefault(e => EqualityComparer.Default.Equals(_getId(e), _getId(entity))); if (existing != null) { - _updatedEntities.Add(entity); if (entities is List list) { + // Explicit external list: apply immediately, never queue — queuing here would + // leak this update into the internal store (or another list) on a later bare + // SaveChanges()/SaveChanges(otherList) call that has nothing to do with this one. var index = list.FindIndex(e => EqualityComparer.Default.Equals(_getId(e), _getId(entity))); if (index >= 0) list[index] = entity; } + else + { + _updatedEntities.Add(entity); + } return entity; } diff --git a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryAggregator.cs b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryAggregator.cs index 2eec9c8..9a32de9 100644 --- a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryAggregator.cs +++ b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryAggregator.cs @@ -22,7 +22,8 @@ TResult EvaluateMin( IEnumerable? entities, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber; /// @@ -38,7 +39,8 @@ TResult EvaluateMax( IEnumerable? entities, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber; /// @@ -54,7 +56,8 @@ decimal EvaluateAverage( IEnumerable? entities, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber; /// @@ -70,7 +73,8 @@ TResult EvaluateSum( IEnumerable? entities, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber; /// @@ -88,6 +92,7 @@ TResult EvaluateAggregate( Func selector, Func aggregator, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber; } diff --git a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryEvaluatorCore.cs b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryEvaluatorCore.cs index 0d80208..2b4998d 100644 --- a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryEvaluatorCore.cs +++ b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryEvaluatorCore.cs @@ -15,7 +15,7 @@ public interface IInMemoryEvaluatorCore where T : class /// The Vali-Flow condition to apply. If null, evaluates to true. /// If true, negates the Vali-Flow condition. /// True if the entity satisfies the condition; otherwise, false. - bool Evaluate(T entity, ValiFlow? valiFlow = null, bool negateCondition = false); + bool Evaluate(T entity, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null); /// /// Determines whether any entity in the collection satisfies the specified Vali-Flow condition. @@ -24,7 +24,7 @@ public interface IInMemoryEvaluatorCore where T : class /// The Vali-Flow condition to apply. If null, evaluates to true for non-empty collections. /// If true, negates the Vali-Flow condition. /// True if at least one entity satisfies the condition; otherwise, false. - bool EvaluateAny(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false); + bool EvaluateAny(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null); /// /// Counts the number of entities in the collection that satisfy the specified Vali-Flow condition. @@ -33,7 +33,7 @@ public interface IInMemoryEvaluatorCore where T : class /// The Vali-Flow condition to apply. If null, counts all entities. /// If true, negates the Vali-Flow condition. /// The number of entities that satisfy the condition. - int EvaluateCount(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false); + int EvaluateCount(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null); /// /// Retrieves the first entity that satisfies the specified Vali-Flow condition. @@ -42,7 +42,7 @@ public interface IInMemoryEvaluatorCore where T : class /// The ValiFlow condition to apply. If null, returns the first entity. /// If true, negates the Vali-Flow condition. /// The first entity that satisfies the condition, or null if none satisfy. - T? GetFirst(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false); + T? GetFirst(IEnumerable? entities = null, ValiFlow? valiFlow = null, bool negateCondition = false, string? tag = null); /// /// Retrieves the first entity that does not satisfy the specified Vali-Flow condition. @@ -50,5 +50,5 @@ public interface IInMemoryEvaluatorCore where T : class /// The collection of entities to evaluate. /// The Vali-Flow condition to apply. If null, returns the first entity. /// The first entity that fails the condition, or null if none fail. - T? GetFirstFailed(IEnumerable? entities = null, ValiFlow? valiFlow = null); + T? GetFirstFailed(IEnumerable? entities = null, ValiFlow? valiFlow = null, string? tag = null); } diff --git a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryGrouping.cs b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryGrouping.cs index 32b62cd..e15a4f6 100644 --- a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryGrouping.cs +++ b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryGrouping.cs @@ -22,7 +22,8 @@ Dictionary> EvaluateGrouped( IEnumerable? entities, Func keySelector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TKey : notnull; /// @@ -38,7 +39,8 @@ Dictionary EvaluateCountByGroup( IEnumerable? entities, Func keySelector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TKey : notnull; /// @@ -57,7 +59,8 @@ Dictionary EvaluateSumByGroup( Func keySelector, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber where TKey : notnull; /// @@ -76,7 +79,8 @@ Dictionary EvaluateMinByGroup( Func keySelector, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber where TKey : notnull; /// @@ -95,7 +99,8 @@ Dictionary EvaluateMaxByGroup( Func keySelector, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber where TKey : notnull; /// @@ -114,7 +119,8 @@ Dictionary EvaluateAverageByGroup( Func keySelector, Func selector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TResult : INumber where TKey : notnull; /// @@ -130,7 +136,8 @@ Dictionary> EvaluateDuplicatesByGroup( IEnumerable? entities, Func keySelector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TKey : notnull; /// @@ -146,7 +153,8 @@ Dictionary EvaluateUniquesByGroup( IEnumerable? entities, Func keySelector, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TKey : notnull; /// @@ -169,6 +177,7 @@ Dictionary> EvaluateTopByGroup( Func? orderBy = null, bool ascending = true, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ) where TKey : notnull; } diff --git a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryQueryable.cs b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryQueryable.cs index d4f3a97..0e58d18 100644 --- a/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryQueryable.cs +++ b/Vali-Flow.InMemory/Interfaces/Evaluators/Read/IInMemoryQueryable.cs @@ -27,7 +27,8 @@ IEnumerable EvaluateAll( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -45,7 +46,8 @@ IEnumerable EvaluateAllFailed( Func? orderBy = null, bool ascending = true, IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null + ValiFlow? valiFlow = null, + string? tag = null ); /// @@ -69,7 +71,8 @@ IEnumerable EvaluatePaged( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -93,7 +96,8 @@ PagedResult EvaluatePagedResult( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -115,7 +119,8 @@ IEnumerable EvaluateTop( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -137,7 +142,8 @@ IEnumerable EvaluateDistinct( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -159,7 +165,8 @@ IEnumerable EvaluateDuplicates( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -179,7 +186,8 @@ int GetFirstMatchIndex( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -199,7 +207,8 @@ int GetLastMatchIndex( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -219,7 +228,8 @@ int GetLastMatchIndex( bool ascending = true, IEnumerable>? thenBys = null, ValiFlow? valiFlow = null, - bool negateCondition = false + bool negateCondition = false, + string? tag = null ); /// @@ -237,6 +247,7 @@ int GetLastMatchIndex( Func? orderBy = null, bool ascending = true, IEnumerable>? thenBys = null, - ValiFlow? valiFlow = null + ValiFlow? valiFlow = null, + string? tag = null ); } diff --git a/Vali-Flow.InMemory/Interfaces/Evaluators/Write/IInMemoryEvaluatorWrite.cs b/Vali-Flow.InMemory/Interfaces/Evaluators/Write/IInMemoryEvaluatorWrite.cs index 9fa3921..9bbc8a0 100644 --- a/Vali-Flow.InMemory/Interfaces/Evaluators/Write/IInMemoryEvaluatorWrite.cs +++ b/Vali-Flow.InMemory/Interfaces/Evaluators/Write/IInMemoryEvaluatorWrite.cs @@ -12,7 +12,7 @@ public interface IInMemoryEvaluatorWrite /// The entity to add. /// The optional list of entities to add to. If null, uses a default context. /// True if the entity was added successfully; otherwise, false. - public bool Add(T entity, List? entities = null); + public bool Add(T entity, List? entities = null, string? tag = null); /// /// Updates a single entity in the specified collection or a default context if no collection is provided. @@ -20,7 +20,7 @@ public interface IInMemoryEvaluatorWrite /// The entity to update. The entity must exist in the collection for the update to succeed. /// The optional list of entities to update within. If null, uses a default context. /// The updated entity if successful, or null if the entity was not found or the update failed. - public T? Update(T entity, List? entities = null); + public T? Update(T entity, List? entities = null, string? tag = null); /// /// Deletes a single entity from the specified collection or a default context if no collection is provided. @@ -28,14 +28,14 @@ public interface IInMemoryEvaluatorWrite /// The entity to delete. The entity must exist in the collection for the deletion to succeed. /// The optional list of entities to delete from. If null, uses a default context. /// True if the entity was deleted successfully; otherwise, false. - public bool Delete(T entity, List? entities = null); + public bool Delete(T entity, List? entities = null, string? tag = null); /// /// Adds a collection of entities to the specified collection or a default context if no collection is provided. /// /// The collection of entities to add. /// The optional list of entities to add to. If null, uses a default context. - public void AddRange(IEnumerable entitiesToAdd, List? entities = null); + public void AddRange(IEnumerable entitiesToAdd, List? entities = null, string? tag = null); /// /// Updates a collection of entities in the specified collection or a default context if no collection is provided. @@ -43,7 +43,7 @@ public interface IInMemoryEvaluatorWrite /// The collection of entities to update. Entities must exist in the collection for updates to succeed. /// The optional list of entities to update within. If null, uses a default context. /// An enumerable of the updated entities. - public IEnumerable UpdateRange(IEnumerable entitiesToUpdate, List? entities = null); + public IEnumerable UpdateRange(IEnumerable entitiesToUpdate, List? entities = null, string? tag = null); /// /// Deletes a collection of entities from the specified collection or a default context if no collection is provided. @@ -54,14 +54,14 @@ public interface IInMemoryEvaluatorWrite /// The number of entities queued for deletion. /// Changes are applied to the store when is called. /// - public int DeleteRange(IEnumerable entitiesToDelete, List? entities = null); + public int DeleteRange(IEnumerable entitiesToDelete, List? entities = null, string? tag = null); /// /// Saves any pending changes to the specified collection or a default context if no collection is provided. /// This method ensures that all previous write operations are applied. /// /// The optional list of entities to save changes for. If null, uses a default context. - public void SaveChanges(List? entities = null); + public void SaveChanges(List? entities = null, string? tag = null); /// /// Inserts the entity if its key is not found in the store; otherwise updates it. @@ -69,7 +69,7 @@ public interface IInMemoryEvaluatorWrite /// The entity to upsert. /// Optional external list. If null, operates on the internal store. /// The upserted entity. - T Upsert(T entity, List? entities = null); + T Upsert(T entity, List? entities = null, string? tag = null); /// /// Upserts each entity in the collection — inserts if the key is new, updates if found. @@ -77,7 +77,7 @@ public interface IInMemoryEvaluatorWrite /// The entities to upsert. /// Optional external list. If null, operates on the internal store. /// The collection of upserted entities. - IEnumerable UpsertRange(IEnumerable entitiesToUpsert, List? entities = null); + IEnumerable UpsertRange(IEnumerable entitiesToUpsert, List? entities = null, string? tag = null); /// /// Deletes all entities that satisfy the given predicate. @@ -85,5 +85,5 @@ public interface IInMemoryEvaluatorWrite /// The condition to match entities for deletion. /// Optional external list. If null, operates on the internal store. /// The number of entities deleted. - int DeleteByCondition(Func predicate, List? entities = null); + int DeleteByCondition(Func predicate, List? entities = null, string? tag = null); } \ No newline at end of file diff --git a/Vali-Flow.InMemory/Vali-Flow.InMemory.csproj b/Vali-Flow.InMemory/Vali-Flow.InMemory.csproj index c4d58c0..b77a356 100644 --- a/Vali-Flow.InMemory/Vali-Flow.InMemory.csproj +++ b/Vali-Flow.InMemory/Vali-Flow.InMemory.csproj @@ -11,7 +11,7 @@ Vali-Flow.InMemory Vali-Flow.InMemory Vali-Flow.InMemory - 1.1.5 + 1.2.0 Felipe Rafael Montenegro Morriberon Copyright © 2026 - FM. All rights reserved. @@ -37,7 +37,9 @@ snupkg Synchronous in-memory evaluator for Vali-Flow.Core — filter, page, aggregate and write in-memory collections using the same fluent ValiFlow<T> specification API. Ideal for unit testing and caching layers without a database dependency. - v1.1.5 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. + v1.2.0 — Fix Update(entity, externalList) leaking into the internal store on a later bare SaveChanges() call. Split ValiFlowEvaluator<T,TProperty> into partial files (Bridge/Read/Write/Grouped). Add an optional tag parameter across read/write/grouped methods, wired to ValiFlowDiagnostics Activity tracing. No breaking changes. + +v1.1.5 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. v1.1.4 — Remove sealed modifiers from all classes (ValiFlowEvaluator, AsyncInMemoryAdapter, InMemoryWriteStore, PagedResult). Now fully inheritable for custom implementations. No breaking changes. @@ -45,7 +47,7 @@ v1.1.4 — Remove sealed modifiers from all classes (ValiFlowEvaluator, AsyncInM - + diff --git a/Vali-Flow.NoSql.CosmosDb.Tests/CosmosFilterTranslatorTests.cs b/Vali-Flow.NoSql.CosmosDb.Tests/CosmosFilterTranslatorTests.cs new file mode 100644 index 0000000..99c7664 --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb.Tests/CosmosFilterTranslatorTests.cs @@ -0,0 +1,461 @@ +using System.Diagnostics; +using System.Linq.Expressions; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.CosmosDb.Extensions; +using Vali_Flow.NoSql.CosmosDb.Models; +using Vali_Flow.NoSql.CosmosDb.Translators; +using Vali_Flow.NoSql.CosmosDb.Tests.Models; +using Vali_Flow.NoSql.IR; + +namespace Vali_Flow.NoSql.CosmosDb.Tests; + +public sealed class CosmosFilterTranslatorTests +{ + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void ToCosmosDb_WithTag_SetsTagAndEntityTypeOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var flow = new ValiFlow().EqualTo(x => x.Name, "Alice"); + + flow.ToCosmosDb(tag: "report-x"); + + captured.Should().NotBeNull(); + captured!.GetTagItem("vali_flow.tag").Should().Be("report-x"); + captured.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestDocument)); + } + + [Fact] + public void Translate_InExceedsMaxValues_SetsErrorStatusOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var values = Enumerable.Range(0, 6_001).Cast().ToList(); + var node = new InNode("Age", values); + + Action act = () => CosmosFilterTranslator.Translate(node); + + act.Should().Throw(); + captured.Should().NotBeNull(); + captured!.Status.Should().Be(ActivityStatusCode.Error); + } + + // ── Equality ────────────────────────────────────────────────────────────── + + [Fact] + public void ToCosmosDb_EqualString_ProducesEqualClause() + { + Expression> expr = x => x.Name == "Alice"; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Name = @p0"); + f.Parameters["@p0"].Should().Be("Alice"); + } + + [Fact] + public void ToCosmosDb_NotEqualString_ProducesNotEqualClause() + { + Expression> expr = x => x.Name != "Bob"; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Name != @p0"); + f.Parameters["@p0"].Should().Be("Bob"); + } + + [Fact] + public void ToCosmosDb_EqualInt_ProducesNumericEqualClause() + { + Expression> expr = x => x.Age == 30; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Age = @p0"); + f.Parameters["@p0"].Should().Be(30); + } + + [Fact] + public void ToCosmosDb_EqualBool_ProducesBoolClause() + { + Expression> expr = x => x.IsActive == true; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.IsActive = @p0"); + f.Parameters["@p0"].Should().Be(true); + } + + [Fact] + public void ToCosmosDb_BoolMemberDirect_ProducesBoolTrueClause() + { + Expression> expr = x => x.IsActive; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.IsActive = @p0"); + f.Parameters["@p0"].Should().Be(true); + } + + // ── Null checks ─────────────────────────────────────────────────────────── + + [Fact] + public void ToCosmosDb_IsNull_ProducesIsNullFunction() + { + Expression> expr = x => x.Email == null; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("IS_NULL(c.Email)"); + f.Parameters.Should().BeEmpty(); + } + + [Fact] + public void ToCosmosDb_IsNotNull_ProducesNotIsNullFunction() + { + Expression> expr = x => x.Email != null; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("NOT IS_NULL(c.Email)"); + } + + // ── Range ───────────────────────────────────────────────────────────────── + + [Fact] + public void ToCosmosDb_GreaterThan_ProducesGtClause() + { + Expression> expr = x => x.Age > 18; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Age > @p0"); + f.Parameters["@p0"].Should().Be(18); + } + + [Fact] + public void ToCosmosDb_GreaterThanOrEqual_ProducesGteClause() + { + Expression> expr = x => x.Age >= 21; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Age >= @p0"); + } + + [Fact] + public void ToCosmosDb_LessThan_ProducesLtClause() + { + Expression> expr = x => x.Age < 65; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Age < @p0"); + } + + [Fact] + public void ToCosmosDb_LessThanOrEqual_ProducesLteClause() + { + Expression> expr = x => x.Age <= 60; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Age <= @p0"); + } + + // ── Pattern match ───────────────────────────────────────────────────────── + + [Fact] + public void ToCosmosDb_StringContains_ProducesContainsFunction() + { + Expression> expr = x => x.Name.Contains("Ali"); + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("CONTAINS(c.Name, @p0)"); + f.Parameters["@p0"].Should().Be("Ali"); + } + + [Fact] + public void ToCosmosDb_StringStartsWith_ProducesStartsWithFunction() + { + Expression> expr = x => x.Name.StartsWith("Al"); + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("STARTSWITH(c.Name, @p0)"); + } + + [Fact] + public void ToCosmosDb_StringEndsWith_ProducesEndsWithFunction() + { + Expression> expr = x => x.Name.EndsWith("ce"); + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("ENDSWITH(c.Name, @p0)"); + f.Parameters["@p0"].Should().Be("ce"); + } + + // ── Membership ──────────────────────────────────────────────────────────── + + [Fact] + public void ToCosmosDb_ListContains_ProducesInClauseWithOnePlaceholderPerValue() + { + var ids = new List { 1, 2, 3 }; + Expression> expr = x => ids.Contains(x.Id); + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Id IN (@p0, @p1, @p2)"); + f.Parameters["@p0"].Should().Be(1); + f.Parameters["@p1"].Should().Be(2); + f.Parameters["@p2"].Should().Be(3); + } + + [Fact] + public void ToCosmosDb_EmptyListContains_ThrowsInvalidOperationException() + { + var ids = new List(); + Expression> expr = x => ids.Contains(x.Id); + + Action act = () => expr.ToCosmosDb(); + + act.Should().Throw().WithMessage("*empty*"); + } + + [Fact] + public void ToCosmosDb_StringListContains_ProducesInClauseWithStringValues() + { + var categories = new List { "Electronics", "Books", "Tools" }; + Expression> expr = x => categories.Contains(x.Category); + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Category IN (@p0, @p1, @p2)"); + f.Parameters["@p0"].Should().Be("Electronics"); + } + + [Fact] + public void ToCosmosDb_ListWithMoreThan6000Items_ThrowsInvalidOperationException() + { + var ids = Enumerable.Range(1, 6001).ToList(); + var node = new InNode("Id", ids.Cast().ToList()); + + Action act = () => CosmosFilterTranslator.Translate(node); + + act.Should().Throw().WithMessage("*6000*"); + } + + [Fact] + public void ToCosmosDb_ListWithExactly6000Items_DoesNotThrow() + { + var ids = Enumerable.Range(1, 6000).ToList(); + var node = new InNode("Id", ids.Cast().ToList()); + + Action act = () => CosmosFilterTranslator.Translate(node); + + act.Should().NotThrow(); + } + + // ── Logical combinators ─────────────────────────────────────────────────── + + [Fact] + public void ToCosmosDb_AndAlso_ProducesAndClause() + { + Expression> expr = x => x.IsActive && x.Age > 18; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("(c.IsActive = @p0 AND c.Age > @p1)"); + f.Parameters.Should().HaveCount(2); + } + + [Fact] + public void ToCosmosDb_OrElse_ProducesOrClause() + { + Expression> expr = x => x.Name == "Alice" || x.Name == "Bob"; + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("(c.Name = @p0 OR c.Name = @p1)"); + } + + [Fact] + public void ToCosmosDb_Not_ProducesNotClause() + { + Expression> expr = x => !(x.Age > 18); + + CosmosFilterExpression f = expr.ToCosmosDb(); + + f.WhereClause.Should().Be("NOT (c.Age > @p0)"); + } + + [Fact] + public void ToCosmosDb_NestedAndOr_ProducesCorrectParentheses() + { + var a = new EqualNode("IsActive", true, false); + var b = new ComparisonNode("Age", 18, ComparisonOp.GreaterThan); + var c = new EqualNode("Name", "Admin", false); + var node = new OrNode(new AndNode(a, b), c); + + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node); + + f.WhereClause.Should().StartWith("("); + f.WhereClause.Should().Contain("AND"); + f.WhereClause.Should().Contain("OR"); + f.WhereClause.Should().MatchRegex(@"\(.*AND.*\).*OR"); + } + + // ── ValiFlow fluent pipeline ─────────────────────────────────────────── + + [Fact] + public void ToCosmosDb_ValiFlowEqualTo_ProducesEqualClause() + { + var flow = new ValiFlow().EqualTo(x => x.Category, "Fruit"); + + CosmosFilterExpression f = flow.ToCosmosDb(); + + f.WhereClause.Should().Be("c.Category = @p0"); + f.Parameters["@p0"].Should().Be("Fruit"); + } + + [Fact] + public void ToCosmosDb_ValiFlowCombined_ProducesAndClause() + { + var flow = new ValiFlow() + .EqualTo(x => x.IsActive, true) + .GreaterThan(x => x.Age, 18); + + CosmosFilterExpression f = flow.ToCosmosDb(); + + f.WhereClause.Should().Be("(c.IsActive = @p0 AND c.Age > @p1)"); + } + + // ── Null guards ─────────────────────────────────────────────────────────── + + [Fact] + public void Translate_NullNode_ThrowsArgumentNullException() + { + Action act = () => CosmosFilterTranslator.Translate(null!); + + act.Should().Throw(); + } + + [Fact] + public void ToCosmosDb_ValiFlowNull_ThrowsArgumentNullException() + { + ValiFlow flow = null!; + + Action act = () => flow.ToCosmosDb(); + + act.Should().Throw(); + } + + [Fact] + public void ToCosmosDb_ExpressionNull_ThrowsArgumentNullException() + { + Expression> expr = null!; + + Action act = () => expr.ToCosmosDb(); + + act.Should().Throw(); + } + + // ── OCP — custom converter ──────────────────────────────────────────────── + + [Fact] + public void CustomConverter_WhenSet_UsedForMatchingType() + { + Func converter = v => v is decimal d ? d.ToString("G", System.Globalization.CultureInfo.InvariantCulture) : null; + + var node = new EqualNode("Price", 9.99m, false); + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node, converter); + + f.Parameters["@p0"].Should().Be("9.99"); + } + + [Fact] + public void CustomConverter_WhenReturnsNull_FallsThroughToDefault() + { + Func converter = _ => null; + + var node = new EqualNode("Name", "Alice", false); + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node, converter); + + f.Parameters["@p0"].Should().Be("Alice"); + } + + // ── Direct node construction / type coverage ────────────────────────────── + + [Fact] + public void Translate_DirectEqualNode_ProducesCorrectClause() + { + var node = new EqualNode("Status", "Active", false); + + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node); + + f.WhereClause.Should().Be("c.Status = @p0"); + f.Parameters["@p0"].Should().Be("Active"); + } + + [Fact] + public void ToCosmosDb_GuidValue_ProducesStringParameter() + { + var guid = Guid.NewGuid(); + var node = new EqualNode("Id", guid, false); + + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node); + + f.Parameters["@p0"].Should().Be(guid.ToString()); + } + + [Fact] + public void ToCosmosDb_EnumValue_ProducesLongParameter() + { + var node = new EqualNode("Status", CosmosTestStatus.Active, false); + + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node); + + f.Parameters["@p0"].Should().Be(1L); + } + + [Fact] + public void ToCosmosDb_DecimalGreaterThan_ProducesNumericComparison() + { + var node = new ComparisonNode("Price", 99.99m, ComparisonOp.GreaterThan); + + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node); + + f.WhereClause.Should().Be("c.Price > @p0"); + f.Parameters["@p0"].Should().Be(99.99m); + } + + [Fact] + public void ToCosmosDb_FallbackTypeObject_ProducesStringParameter() + { + var node = new EqualNode("Misc", new Uri("https://example.com"), false); + + CosmosFilterExpression f = CosmosFilterTranslator.Translate(node); + + f.Parameters["@p0"].Should().Be("https://example.com/"); + } + + private enum CosmosTestStatus { Active = 1 } +} diff --git a/Vali-Flow.NoSql.CosmosDb.Tests/Models/TestDocument.cs b/Vali-Flow.NoSql.CosmosDb.Tests/Models/TestDocument.cs new file mode 100644 index 0000000..a899415 --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb.Tests/Models/TestDocument.cs @@ -0,0 +1,12 @@ +namespace Vali_Flow.NoSql.CosmosDb.Tests.Models; + +public sealed class TestDocument +{ + public int Id { get; set; } + public string Name { get; set; } = string.Empty; + public string? Email { get; set; } + public int Age { get; set; } + public decimal Price { get; set; } + public bool IsActive { get; set; } + public string Category { get; set; } = string.Empty; +} diff --git a/Vali-Flow.NoSql.CosmosDb.Tests/Vali-Flow.NoSql.CosmosDb.Tests.csproj b/Vali-Flow.NoSql.CosmosDb.Tests/Vali-Flow.NoSql.CosmosDb.Tests.csproj new file mode 100644 index 0000000..da9c46c --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb.Tests/Vali-Flow.NoSql.CosmosDb.Tests.csproj @@ -0,0 +1,29 @@ + + + net9.0 + enable + enable + false + Vali_Flow.NoSql.CosmosDb.Tests + + + + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + + + + + + + + diff --git a/Vali-Flow.NoSql.CosmosDb/CHANGELOG.md b/Vali-Flow.NoSql.CosmosDb/CHANGELOG.md new file mode 100644 index 0000000..55e3a7d --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb/CHANGELOG.md @@ -0,0 +1,19 @@ +# Changelog — Vali-Flow.NoSql.CosmosDb + +All notable changes to this package are documented here. +Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning: [SemVer](https://semver.org/) + +--- + +## [Unreleased] + +--- + +## [1.0.0] — Initial release + +### Added +- `CosmosFilterExpression` — translates Vali-Flow IR nodes into an Azure Cosmos DB SQL API WHERE clause fragment plus a parameter dictionary, with no dependency on the `Microsoft.Azure.Cosmos` SDK +- Support for: equality, comparison, AND/OR/NOT, IN list, CONTAINS/STARTSWITH/ENDSWITH (native Cosmos SQL functions), IS_NULL/NOT IS_NULL +- `ValiFlowCosmosDbExtensions.ToCosmosDb()` — extension methods on `ValiFlow` and `Expression>` +- Custom value converter hook for domain types not covered by the built-in CLR type mapping +- XML documentation on all public types and members diff --git a/Vali-Flow.NoSql.CosmosDb/Extensions/ValiFlowCosmosDbExtensions.cs b/Vali-Flow.NoSql.CosmosDb/Extensions/ValiFlowCosmosDbExtensions.cs new file mode 100644 index 0000000..f64ac6a --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb/Extensions/ValiFlowCosmosDbExtensions.cs @@ -0,0 +1,57 @@ +using System.Linq.Expressions; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.CosmosDb.Models; +using Vali_Flow.NoSql.CosmosDb.Translators; +using Vali_Flow.NoSql.Extensions; + +namespace Vali_Flow.NoSql.CosmosDb.Extensions; + +/// +/// Extension methods that add Azure Cosmos DB SQL API WHERE-clause-building capabilities to . +/// +/// +/// The returned encapsulates the WHERE clause fragment and the +/// parameter dictionary for use with a Cosmos SQL QueryDefinition. +/// This package depends only on Vali-Flow.NoSql — +/// it is a query builder with no connection, SDK, or execution concerns. +/// +public static class ValiFlowCosmosDbExtensions +{ + /// + /// Translates the conditions built in this instance + /// into an Azure Cosmos DB . + /// + /// The entity / document type. + /// The ValiFlow builder containing the conditions. + /// Optional override to convert a value into its raw Cosmos parameter value for types the default conversion doesn't handle. + /// A ready to append to a Cosmos SQL query. + /// + /// + /// var filter = new ValiFlow<Order>() + /// .EqualTo(x => x.Status, "Active") + /// .GreaterThan(x => x.Total, 100m); + /// + /// CosmosFilterExpression f = filter.ToCosmosDb(); + /// var queryText = $"SELECT * FROM c WHERE {f.WhereClause}"; + /// var query = new QueryDefinition(queryText); + /// foreach (var kv in f.Parameters) query = query.WithParameter(kv.Key, kv.Value); + /// + /// + public static CosmosFilterExpression ToCosmosDb(this ValiFlow flow, Func? customConverter = null, string? tag = null) where T : class + { + if (flow == null) throw new ArgumentNullException(nameof(flow)); + + return CosmosFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter, tag, typeof(T).Name); + } + + /// + /// Translates a prebuilt into an Azure Cosmos DB . + /// Use this overload when you already have a compiled expression. + /// + public static CosmosFilterExpression ToCosmosDb(this Expression> expression, Func? customConverter = null, string? tag = null) + { + if (expression == null) throw new ArgumentNullException(nameof(expression)); + + return CosmosFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter, tag, typeof(T).Name); + } +} diff --git a/Vali-Flow.NoSql.CosmosDb/Models/CosmosFilterExpression.cs b/Vali-Flow.NoSql.CosmosDb/Models/CosmosFilterExpression.cs new file mode 100644 index 0000000..4f25dbb --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb/Models/CosmosFilterExpression.cs @@ -0,0 +1,28 @@ +namespace Vali_Flow.NoSql.CosmosDb.Models; + +/// +/// Encapsulates the result of translating a Vali-Flow filter into a Cosmos DB SQL API WHERE clause fragment. +/// +/// +/// Pass the two properties directly when building a Cosmos SQL query: +/// +/// var cosmos = filter.ToCosmosDb(); +/// var queryText = $"SELECT * FROM c WHERE {cosmos.WhereClause}"; +/// var query = new QueryDefinition(queryText); +/// foreach (var kv in cosmos.Parameters) query = query.WithParameter(kv.Key, kv.Value); +/// +/// +public sealed class CosmosFilterExpression +{ + /// The WHERE clause fragment, without the leading "WHERE" keyword (e.g. "c.Age > @p0"). + public string WhereClause { get; } + + /// Mapping from parameter placeholders (@p0) to their values. + public IReadOnlyDictionary Parameters { get; } + + internal CosmosFilterExpression(string whereClause, Dictionary parameters) + { + WhereClause = whereClause; + Parameters = parameters.AsReadOnly(); + } +} diff --git a/Vali-Flow.NoSql.CosmosDb/README.md b/Vali-Flow.NoSql.CosmosDb/README.md new file mode 100644 index 0000000..1c69205 --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb/README.md @@ -0,0 +1,46 @@ +# Vali-Flow.NoSql.CosmosDb + +Azure Cosmos DB SQL API WHERE-clause builder that translates `ValiFlow` filters into native `CosmosFilterExpression` objects. + +See the [main README](../../README.md) for complete documentation and examples. + +## Installation + +```bash +dotnet add package Vali-Flow.NoSql.CosmosDb +``` + +## Quick Example + +```csharp +using Vali_Flow.NoSql.CosmosDb.Extensions; + +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Active") + .GreaterThan(x => x.Total, 100m); + +CosmosFilterExpression f = filter.ToCosmosDb(); + +var queryText = $"SELECT * FROM c WHERE {f.WhereClause}"; +var query = new QueryDefinition(queryText); +foreach (var kv in f.Parameters) query = query.WithParameter(kv.Key, kv.Value); + +using var iterator = container.GetItemQueryIterator(query); +``` + +## Features + +- Translates `ValiFlow` expressions to a Cosmos SQL API WHERE clause fragment +- Native functions: `CONTAINS`, `STARTSWITH`, `ENDSWITH`, `IS_NULL` +- Parameter placeholders (`@p0`, `@p1`, …), one per value — no attribute-name placeholders needed +- No dependency on the `Microsoft.Azure.Cosmos` SDK — pure string/parameter builder + +## Limitations + +- Does not depend on the Cosmos SDK — it only produces the WHERE fragment. You build your own `QueryDefinition` / `Container.GetItemQueryIterator` with it. +- `In` with an empty list throws `InvalidOperationException` — filter the empty case before building the query. +- No upper bound is enforced on `In` list size by this package; very large lists may still hit Cosmos DB's own query size/complexity limits. + +## License + +MIT diff --git a/Vali-Flow.NoSql.CosmosDb/Translators/CosmosFilterTranslator.cs b/Vali-Flow.NoSql.CosmosDb/Translators/CosmosFilterTranslator.cs new file mode 100644 index 0000000..79b3641 --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb/Translators/CosmosFilterTranslator.cs @@ -0,0 +1,188 @@ +using System.Globalization; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.NoSql.CosmosDb.Models; +using Vali_Flow.NoSql.IR; +using Vali_Flow.NoSql.Translators; + +namespace Vali_Flow.NoSql.CosmosDb.Translators; + +/// +/// Translates a IR tree into an Azure Cosmos DB SQL API +/// — a parameterized WHERE clause fragment. +/// +/// +/// The result uses the standard Cosmos SQL container alias c (e.g. c.Age) and +/// SQL Server-style @p0 parameter placeholders, ready to append to a query text and +/// bind via QueryDefinition.WithParameter. +/// +/// Mapping notes: +/// +/// maps to the native CONTAINS/STARTSWITH/ENDSWITH functions. +/// maps to the native IS_NULL function. +/// expands to one placeholder per value — Cosmos SQL does not accept a single array parameter for IN. +/// +/// +/// +public static class CosmosFilterTranslator +{ + private const string ContainerAlias = "c."; + + // Cosmos SQL expands every IN value into its own @pN placeholder, consuming the query's + // documented 512KB max query size and its parameter-count budget alongside other params in the + // same query. No official per-element IN limit is documented — this is a conservative practical + // cap, not an exact Cosmos limit. + private const int MaxInValues = 6_000; + + /// + /// Translates the given into a . + /// + /// The root condition node to translate. + /// + /// Optional hook for converting custom CLR types into the raw value stored in the parameters dictionary. + /// Called before the built-in type switch. Return null to fall through to the default conversion. + /// Thread-safe: the converter is scoped to this call only. + /// + /// A ready to append to a Cosmos SQL query. + public static CosmosFilterExpression Translate(IConditionNode node, Func? customConverter = null, string? tag = null, string? entityType = null) + { + if (node == null) throw new ArgumentNullException(nameof(node)); + + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.NoSql.CosmosDb.Translate", tag, entityType); + try + { + var ctx = new TranslationContext(); + var visitor = new CosmosVisitor(ctx, customConverter); + var expression = node.Accept(visitor); + return new CosmosFilterExpression(expression, ctx.Parameters); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private sealed class CosmosVisitor(TranslationContext ctx, Func? customConverter) + : IConditionNodeVisitor + { + public string VisitAnd(AndNode node) => + $"({node.Left.Accept(this)} AND {node.Right.Accept(this)})"; + + public string VisitOr(OrNode node) => + $"({node.Left.Accept(this)} OR {node.Right.Accept(this)})"; + + public string VisitNot(NotNode node) => + $"NOT ({node.Inner.Accept(this)})"; + + public string VisitNull(NullNode node) => NullHelper.Build(node); + + public string VisitEqual(EqualNode node) => EqualHelper.Build(node, ctx, customConverter); + + public string VisitComparison(ComparisonNode node) => ComparisonHelper.Build(node, ctx, customConverter); + + public string VisitLike(LikeNode node) => LikeHelper.Build(node, ctx); + + public string VisitIn(InNode node) => InHelper.Build(node, ctx, customConverter); + } + + // ── Node-specific builders (kept tiny, one responsibility each) ────────── + + private static class NullHelper + { + public static string Build(NullNode node) => + node.Check == NullCheckOp.IsNull + ? $"IS_NULL({Field(node.Field)})" + : $"NOT IS_NULL({Field(node.Field)})"; + } + + private static class EqualHelper + { + public static string Build(EqualNode node, TranslationContext ctx, Func? customConverter) + { + var placeholder = ctx.AddParameter(ConvertValue(node.Value, customConverter)); + return node.IsNegated + ? $"{Field(node.Field)} != {placeholder}" + : $"{Field(node.Field)} = {placeholder}"; + } + } + + private static class ComparisonHelper + { + public static string Build(ComparisonNode node, TranslationContext ctx, Func? customConverter) => + $"{Field(node.Field)} {MapComparisonOp(node.Op)} {ctx.AddParameter(ConvertValue(node.Value, customConverter))}"; + + private static string MapComparisonOp(ComparisonOp op) => op switch + { + ComparisonOp.GreaterThan => ">", + ComparisonOp.GreaterThanOrEqual => ">=", + ComparisonOp.LessThan => "<", + ComparisonOp.LessThanOrEqual => "<=", + _ => throw new NotSupportedException($"ComparisonOp.{op} is not mapped.") + }; + } + + private static class LikeHelper + { + public static string Build(LikeNode node, TranslationContext ctx) => node.Op switch + { + LikeOp.Contains => $"CONTAINS({Field(node.Field)}, {ctx.AddParameter(node.Pattern)})", + LikeOp.StartsWith => $"STARTSWITH({Field(node.Field)}, {ctx.AddParameter(node.Pattern)})", + LikeOp.EndsWith => $"ENDSWITH({Field(node.Field)}, {ctx.AddParameter(node.Pattern)})", + _ => throw new NotSupportedException($"LikeOp.{node.Op} is not mapped.") + }; + } + + private static class InHelper + { + public static string Build(InNode node, TranslationContext ctx, Func? customConverter) + { + if (node.Values.Count == 0) + throw new InvalidOperationException( + "IN condition with empty list is not supported in Cosmos DB SQL queries. Filter the empty case before building the query."); + + if (node.Values.Count > MaxInValues) + throw new InvalidOperationException( + $"Cosmos DB SQL IN expression supports at most {MaxInValues} values (conservative practical " + + $"limit — each value consumes a placeholder against the 512KB max query size and the query's " + + $"parameter budget); received {node.Values.Count}. Split the query or batch the values."); + + var field = Field(node.Field); + var placeholders = node.Values.Select(v => ctx.AddParameter(ConvertValue(v, customConverter))); + return $"{field} IN ({string.Join(", ", placeholders)})"; + } + } + + private static string Field(string fieldName) => $"{ContainerAlias}{fieldName}"; + + private static object? ConvertValue(object? value, Func? customConverter) => + ConditionValueResolver.Resolve(value, customConverter, v => v switch + { + null => null, + bool b => b, + string s => s, + int i => i, + long l => l, + double d => d, + float f => f, + decimal m => m, + Guid g => g.ToString(), + Enum e => Convert.ToInt64(e, CultureInfo.InvariantCulture), + _ => v!.ToString()! + }); + + // ── Private translation context (NOT part of public API) ───────────────── + + private sealed class TranslationContext + { + private int _paramCounter; + + public Dictionary Parameters { get; } = new(); + + public string AddParameter(object? value) + { + var placeholder = $"@p{_paramCounter++}"; + Parameters[placeholder] = value; + return placeholder; + } + } +} diff --git a/Vali-Flow.NoSql.CosmosDb/VF_logo.png b/Vali-Flow.NoSql.CosmosDb/VF_logo.png new file mode 100644 index 0000000..1e093e9 Binary files /dev/null and b/Vali-Flow.NoSql.CosmosDb/VF_logo.png differ diff --git a/Vali-Flow.NoSql.CosmosDb/Vali-Flow.NoSql.CosmosDb.csproj b/Vali-Flow.NoSql.CosmosDb/Vali-Flow.NoSql.CosmosDb.csproj new file mode 100644 index 0000000..94cd3a9 --- /dev/null +++ b/Vali-Flow.NoSql.CosmosDb/Vali-Flow.NoSql.CosmosDb.csproj @@ -0,0 +1,47 @@ + + + + net8.0;net9.0 + enable + enable + Vali_Flow.NoSql.CosmosDb + Vali-Flow.NoSql.CosmosDb + 1.1.0 + Felipe Rafael Montenegro Morriberon + Vali-Flow.NoSql.CosmosDb + Azure Cosmos DB (SQL API) adapter for Vali-Flow.NoSql — translates the provider-agnostic IR tree into a parameterized Cosmos SQL WHERE clause fragment. Use .ToCosmosDb() on any ValiFlow<T> or Expression<Func<T, bool>>. + Copyright © 2026 - FM. Todos los derechos reservados. + MIT + true + https://vali-flow-docs.netlify.app/docs/adapters/nosql/cosmosdb/overview + https://github.com/UBF21/vali-flow + git + VF_logo.png + README.md + vali;vali-flow;cosmosdb;azure;sql-api;filter;nosql;dotnet + v1.1.0 — Add a MaxInValues cap. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. + true + true + true + embedded + true + snupkg + + + + + True + + + + True + + + + + + + + + + diff --git a/Vali-Flow.NoSql.Couchbase.Tests/CouchbaseFilterTranslatorTests.cs b/Vali-Flow.NoSql.Couchbase.Tests/CouchbaseFilterTranslatorTests.cs new file mode 100644 index 0000000..9ff5743 --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase.Tests/CouchbaseFilterTranslatorTests.cs @@ -0,0 +1,425 @@ +using System.Diagnostics; +using System.Linq.Expressions; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Couchbase.Extensions; +using Vali_Flow.NoSql.Couchbase.Models; +using Vali_Flow.NoSql.Couchbase.Translators; +using Vali_Flow.NoSql.Couchbase.Tests.Models; +using Vali_Flow.NoSql.IR; + +namespace Vali_Flow.NoSql.Couchbase.Tests; + +public sealed class CouchbaseFilterTranslatorTests +{ + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void ToCouchbase_WithTag_SetsTagAndEntityTypeOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var flow = new ValiFlow().EqualTo(x => x.Name, "Alice"); + + flow.ToCouchbase(tag: "report-x"); + + captured.Should().NotBeNull(); + captured!.GetTagItem("vali_flow.tag").Should().Be("report-x"); + captured.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestDocument)); + } + + [Fact] + public void Translate_InExceedsMaxValues_SetsErrorStatusOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var values = Enumerable.Range(0, 10_001).Cast().ToList(); + var node = new InNode("Age", values); + + Action act = () => CouchbaseFilterTranslator.Translate(node); + + act.Should().Throw(); + captured.Should().NotBeNull(); + captured!.Status.Should().Be(ActivityStatusCode.Error); + } + + // ── Equality ────────────────────────────────────────────────────────────── + + [Fact] + public void ToCouchbase_EqualString_ProducesEqualClause() + { + Expression> expr = x => x.Name == "Alice"; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Name` = $p0"); + f.Parameters["$p0"].Should().Be("Alice"); + } + + [Fact] + public void ToCouchbase_NotEqualString_ProducesNotEqualClause() + { + Expression> expr = x => x.Name != "Bob"; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Name` <> $p0"); + f.Parameters["$p0"].Should().Be("Bob"); + } + + [Fact] + public void ToCouchbase_EqualInt_ProducesEqualClause() + { + Expression> expr = x => x.Age == 30; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Age` = $p0"); + f.Parameters["$p0"].Should().Be(30); + } + + [Fact] + public void ToCouchbase_EqualBool_ProducesEqualClause() + { + Expression> expr = x => x.IsActive == true; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`IsActive` = $p0"); + f.Parameters["$p0"].Should().Be(true); + } + + // ── Null checks ─────────────────────────────────────────────────────────── + + [Fact] + public void ToCouchbase_IsNull_ProducesIsNullClause() + { + Expression> expr = x => x.Email == null; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Email` IS NULL"); + f.Parameters.Should().BeEmpty(); + } + + [Fact] + public void ToCouchbase_IsNotNull_ProducesIsNotNullClause() + { + Expression> expr = x => x.Email != null; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Email` IS NOT NULL"); + } + + // ── Range ───────────────────────────────────────────────────────────────── + + [Fact] + public void ToCouchbase_GreaterThan_ProducesGtClause() + { + Expression> expr = x => x.Age > 18; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Age` > $p0"); + f.Parameters["$p0"].Should().Be(18); + } + + [Fact] + public void ToCouchbase_GreaterThanOrEqual_ProducesGteClause() + { + Expression> expr = x => x.Age >= 21; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Age` >= $p0"); + } + + [Fact] + public void ToCouchbase_LessThan_ProducesLtClause() + { + Expression> expr = x => x.Age < 65; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Age` < $p0"); + } + + [Fact] + public void ToCouchbase_LessThanOrEqual_ProducesLteClause() + { + Expression> expr = x => x.Age <= 60; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Age` <= $p0"); + } + + // ── Pattern match ───────────────────────────────────────────────────────── + + [Fact] + public void ToCouchbase_StringContains_ProducesLikeWithBothWildcards() + { + Expression> expr = x => x.Name.Contains("Ali"); + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Name` LIKE $p0"); + f.Parameters["$p0"].Should().Be("%Ali%"); + } + + [Fact] + public void ToCouchbase_StringStartsWith_ProducesLikeWithTrailingWildcard() + { + Expression> expr = x => x.Name.StartsWith("Al"); + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Name` LIKE $p0"); + f.Parameters["$p0"].Should().Be("Al%"); + } + + [Fact] + public void ToCouchbase_StringEndsWith_ProducesLikeWithLeadingWildcard() + { + Expression> expr = x => x.Name.EndsWith("ce"); + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Name` LIKE $p0"); + f.Parameters["$p0"].Should().Be("%ce"); + } + + // ── Membership ──────────────────────────────────────────────────────────── + + [Fact] + public void ToCouchbase_ListContains_ProducesInClauseWithArrayParameter() + { + var ids = new List { 1, 2, 3 }; + Expression> expr = x => ids.Contains(x.Id); + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("`Id` IN $p0"); + f.Parameters["$p0"].Should().BeEquivalentTo(new List { 1, 2, 3 }); + } + + [Fact] + public void ToCouchbase_EmptyListContains_ThrowsInvalidOperationException() + { + var ids = new List(); + Expression> expr = x => ids.Contains(x.Id); + + Action act = () => expr.ToCouchbase(); + + act.Should().Throw().WithMessage("*empty*"); + } + + [Fact] + public void ToCouchbase_ListWithMoreThan10000Items_ThrowsInvalidOperationException() + { + var ids = Enumerable.Range(1, 10_001).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => CouchbaseFilterTranslator.Translate(node); + + act.Should().Throw().WithMessage("*10000*"); + } + + [Fact] + public void ToCouchbase_ListWithExactly10000Items_DoesNotThrow() + { + var ids = Enumerable.Range(1, 10_000).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => CouchbaseFilterTranslator.Translate(node); + + act.Should().NotThrow(); + } + + // ── Logical combinators ─────────────────────────────────────────────────── + + [Fact] + public void ToCouchbase_AndAlso_ProducesAndClause() + { + Expression> expr = x => x.IsActive && x.Age > 18; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("(`IsActive` = $p0 AND `Age` > $p1)"); + } + + [Fact] + public void ToCouchbase_OrElse_ProducesOrClause() + { + Expression> expr = x => x.Name == "Alice" || x.Name == "Bob"; + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("(`Name` = $p0 OR `Name` = $p1)"); + } + + [Fact] + public void ToCouchbase_Not_ProducesNotClause() + { + Expression> expr = x => !(x.Age > 18); + + CouchbaseFilterExpression f = expr.ToCouchbase(); + + f.WhereClause.Should().Be("NOT (`Age` > $p0)"); + } + + [Fact] + public void ToCouchbase_NestedAndOr_ProducesCorrectParentheses() + { + var a = new EqualNode("IsActive", true, false); + var b = new ComparisonNode("Age", 18, ComparisonOp.GreaterThan); + var c = new EqualNode("Name", "Admin", false); + var node = new OrNode(new AndNode(a, b), c); + + CouchbaseFilterExpression f = CouchbaseFilterTranslator.Translate(node); + + f.WhereClause.Should().Be("((`IsActive` = $p0 AND `Age` > $p1) OR `Name` = $p2)"); + } + + // ── ValiFlow fluent pipeline ─────────────────────────────────────────── + + [Fact] + public void ToCouchbase_ValiFlowEqualTo_ProducesEqualClause() + { + var flow = new ValiFlow().EqualTo(x => x.Category, "Fruit"); + + CouchbaseFilterExpression f = flow.ToCouchbase(); + + f.WhereClause.Should().Be("`Category` = $p0"); + f.Parameters["$p0"].Should().Be("Fruit"); + } + + [Fact] + public void ToCouchbase_ValiFlowCombined_ProducesAndClause() + { + var flow = new ValiFlow() + .EqualTo(x => x.IsActive, true) + .GreaterThan(x => x.Age, 18); + + CouchbaseFilterExpression f = flow.ToCouchbase(); + + f.WhereClause.Should().Be("(`IsActive` = $p0 AND `Age` > $p1)"); + } + + // ── Null guards ─────────────────────────────────────────────────────────── + + [Fact] + public void Translate_NullNode_ThrowsArgumentNullException() + { + Action act = () => CouchbaseFilterTranslator.Translate(null!); + + act.Should().Throw(); + } + + [Fact] + public void ToCouchbase_ValiFlowNull_ThrowsArgumentNullException() + { + ValiFlow flow = null!; + + Action act = () => flow.ToCouchbase(); + + act.Should().Throw(); + } + + [Fact] + public void ToCouchbase_ExpressionNull_ThrowsArgumentNullException() + { + Expression> expr = null!; + + Action act = () => expr.ToCouchbase(); + + act.Should().Throw(); + } + + // ── OCP — custom converter ──────────────────────────────────────────────── + + [Fact] + public void CustomConverter_WhenSet_UsedForMatchingType() + { + Func converter = v => v is decimal d ? $"DEC:{d}" : null; + + var node = new EqualNode("Price", 9.99m, false); + CouchbaseFilterExpression f = CouchbaseFilterTranslator.Translate(node, converter); + + f.Parameters["$p0"].Should().Be("DEC:9.99"); + } + + [Fact] + public void CustomConverter_WhenReturnsNull_FallsThroughToDefault() + { + Func converter = _ => null; + + var node = new EqualNode("Name", "Alice", false); + CouchbaseFilterExpression f = CouchbaseFilterTranslator.Translate(node, converter); + + f.Parameters["$p0"].Should().Be("Alice"); + } + + // ── Type coverage ───────────────────────────────────────────────────────── + + [Fact] + public void ToCouchbase_DecimalValue_ProducesNumericParameter() + { + // Regression: N1QL has no implicit coercion between string and number — a decimal + // bound as a string silently matched zero rows against a numeric field for every + // comparison op, confirmed against a real Couchbase cluster. Must bind as a number. + var node = new EqualNode("Price", 9.99m, false); + + CouchbaseFilterExpression f = CouchbaseFilterTranslator.Translate(node); + + f.Parameters["$p0"].Should().Be(9.99m); + f.Parameters["$p0"].Should().BeOfType(); + } + + [Fact] + public void ToCouchbase_GuidValue_ProducesStringParameter() + { + var guid = Guid.NewGuid(); + var node = new EqualNode("Id", guid, false); + + CouchbaseFilterExpression f = CouchbaseFilterTranslator.Translate(node); + + f.Parameters["$p0"].Should().Be(guid.ToString()); + } + + [Fact] + public void ToCouchbase_EnumValue_ProducesLongParameter() + { + var node = new EqualNode("Status", CouchbaseTestStatus.Active, false); + + CouchbaseFilterExpression f = CouchbaseFilterTranslator.Translate(node); + + f.Parameters["$p0"].Should().Be(1L); + } + + [Fact] + public void ToCouchbase_FallbackTypeObject_ProducesStringParameter() + { + var node = new EqualNode("Misc", new Uri("https://example.com"), false); + + CouchbaseFilterExpression f = CouchbaseFilterTranslator.Translate(node); + + f.Parameters["$p0"].Should().Be("https://example.com/"); + } + + private enum CouchbaseTestStatus { Active = 1 } +} diff --git a/Vali-Flow.NoSql.Couchbase.Tests/Models/TestDocument.cs b/Vali-Flow.NoSql.Couchbase.Tests/Models/TestDocument.cs new file mode 100644 index 0000000..4768389 --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase.Tests/Models/TestDocument.cs @@ -0,0 +1,12 @@ +namespace Vali_Flow.NoSql.Couchbase.Tests.Models; + +public sealed class TestDocument +{ + public int Id { get; set; } + public string Name { get; set; } = string.Empty; + public string? Email { get; set; } + public int Age { get; set; } + public decimal Price { get; set; } + public bool IsActive { get; set; } + public string Category { get; set; } = string.Empty; +} diff --git a/Vali-Flow.NoSql.Couchbase.Tests/Vali-Flow.NoSql.Couchbase.Tests.csproj b/Vali-Flow.NoSql.Couchbase.Tests/Vali-Flow.NoSql.Couchbase.Tests.csproj new file mode 100644 index 0000000..8095a9c --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase.Tests/Vali-Flow.NoSql.Couchbase.Tests.csproj @@ -0,0 +1,29 @@ + + + net9.0 + enable + enable + false + Vali_Flow.NoSql.Couchbase.Tests + + + + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + + + + + + + + diff --git a/Vali-Flow.NoSql.Couchbase/CHANGELOG.md b/Vali-Flow.NoSql.Couchbase/CHANGELOG.md new file mode 100644 index 0000000..1d1d90e --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase/CHANGELOG.md @@ -0,0 +1,19 @@ +# Changelog — Vali-Flow.NoSql.Couchbase + +All notable changes to this package are documented here. +Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning: [SemVer](https://semver.org/) + +--- + +## [Unreleased] + +--- + +## [1.0.0] — Initial release + +### Added +- `CouchbaseFilterExpression` — sealed class exposing `WhereClause` (string, no leading `WHERE`) and `Parameters` (`IReadOnlyDictionary`, named `$p0`, `$p1`, …) +- `ValiFlowCouchbaseExtensions.ToCouchbase()` — extension method on `ValiFlow` and on a pre-built `Expression>` +- Support for: equality, comparison (`GreaterThan`/`GreaterThanOrEqualTo`/`LessThan`/`LessThanOrEqualTo`), AND/OR/NOT, IN (bound as a single array parameter), LIKE (`Contains`/`StartsWith`/`EndsWith`), null checks +- `customConverter` hook for mapping CLR types not handled by the built-in value-resolution switch +- No dependency on the Couchbase .NET SDK — pure N1QL text/parameter builder, no connection or execution concerns diff --git a/Vali-Flow.NoSql.Couchbase/Extensions/ValiFlowCouchbaseExtensions.cs b/Vali-Flow.NoSql.Couchbase/Extensions/ValiFlowCouchbaseExtensions.cs new file mode 100644 index 0000000..6d77e3f --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase/Extensions/ValiFlowCouchbaseExtensions.cs @@ -0,0 +1,58 @@ +using System.Linq.Expressions; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Couchbase.Models; +using Vali_Flow.NoSql.Couchbase.Translators; +using Vali_Flow.NoSql.Extensions; + +namespace Vali_Flow.NoSql.Couchbase.Extensions; + +/// +/// Extension methods that add Couchbase N1QL (SQL++) WHERE-clause-building capabilities +/// to . +/// +/// +/// The returned encapsulates the WHERE clause fragment +/// and named parameter dictionary for use with a N1QL query. This package depends only on +/// Vali-Flow.NoSql — it is a query builder with no Couchbase SDK or connection concerns. +/// +public static class ValiFlowCouchbaseExtensions +{ + /// + /// Translates the conditions built in this instance + /// into a Couchbase . + /// + /// The entity / document type. + /// The ValiFlow builder containing the conditions. + /// Optional override to convert a value into the N1QL parameter value for types the default conversion doesn't handle. + /// A ready to bind to a N1QL query. + /// + /// + /// var filter = new ValiFlow<Order>() + /// .EqualTo(x => x.Status, "Active") + /// .GreaterThan(x => x.Total, 100m); + /// + /// CouchbaseFilterExpression f = filter.ToCouchbase(); + /// var query = $"SELECT * FROM `orders` WHERE {f.WhereClause}"; + /// var options = new QueryOptions(); + /// foreach (var (name, value) in f.Parameters) + /// options.Parameter(name, value); + /// + /// + public static CouchbaseFilterExpression ToCouchbase(this ValiFlow flow, Func? customConverter = null, string? tag = null) where T : class + { + if (flow == null) throw new ArgumentNullException(nameof(flow)); + + return CouchbaseFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter, tag, typeof(T).Name); + } + + /// + /// Translates a prebuilt into a Couchbase . + /// Use this overload when you already have a compiled expression. + /// + public static CouchbaseFilterExpression ToCouchbase(this Expression> expression, Func? customConverter = null, string? tag = null) + { + if (expression == null) throw new ArgumentNullException(nameof(expression)); + + return CouchbaseFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter, tag, typeof(T).Name); + } +} diff --git a/Vali-Flow.NoSql.Couchbase/Models/CouchbaseFilterExpression.cs b/Vali-Flow.NoSql.Couchbase/Models/CouchbaseFilterExpression.cs new file mode 100644 index 0000000..021534c --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase/Models/CouchbaseFilterExpression.cs @@ -0,0 +1,34 @@ +namespace Vali_Flow.NoSql.Couchbase.Models; + +/// +/// Encapsulates the result of translating a Vali-Flow filter into a Couchbase N1QL (SQL++) WHERE clause. +/// +/// +/// Couchbase has no "native" filter object like MongoDB's BsonDocument or DynamoDB's AttributeValue — +/// N1QL is plain parameterized text, the same approach as SQL. Combine with +/// a full N1QL statement and bind as named parameters ($p0, $p1, ...): +/// +/// var filter = flow.ToCouchbase(); +/// var query = $"SELECT * FROM `bucket` WHERE {filter.WhereClause}"; +/// var options = new QueryOptions(); +/// foreach (var (name, value) in filter.Parameters) +/// options.Parameter(name, value); +/// +/// +public sealed class CouchbaseFilterExpression +{ + /// + /// The N1QL WHERE clause fragment (without the leading WHERE keyword), + /// e.g. "`Name` = $p0". + /// + public string WhereClause { get; } + + /// Named N1QL parameters ($p0, $p1, ...) to bind to the query. + public IReadOnlyDictionary Parameters { get; } + + internal CouchbaseFilterExpression(string whereClause, Dictionary parameters) + { + WhereClause = whereClause; + Parameters = parameters.AsReadOnly(); + } +} diff --git a/Vali-Flow.NoSql.Couchbase/README.md b/Vali-Flow.NoSql.Couchbase/README.md new file mode 100644 index 0000000..edae4c8 --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase/README.md @@ -0,0 +1,48 @@ +# Vali-Flow.NoSql.Couchbase + +Couchbase N1QL (SQL++) WHERE-clause builder that translates `ValiFlow` filters into a parameterized `CouchbaseFilterExpression`. + +See the [main README](../../README.md) for complete documentation and examples. + +## Installation + +```bash +dotnet add package Vali-Flow.NoSql.Couchbase +``` + +## Quick Example + +```csharp +using Vali_Flow.NoSql.Couchbase.Extensions; + +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Active") + .GreaterThan(x => x.Total, 100m); + +CouchbaseFilterExpression f = filter.ToCouchbase(); + +var query = $"SELECT * FROM `orders` WHERE {f.WhereClause}"; +var options = new QueryOptions(); +foreach (var (name, value) in f.Parameters) + options.Parameter(name, value); + +var result = await cluster.QueryAsync(query, options); +``` + +## Features + +- Translates `ValiFlow` expressions to a N1QL WHERE clause fragment +- Named parameters (`$p0`, `$p1`, …) instead of inline literals +- Backtick-quoted identifiers (`` `field` ``), N1QL/MySQL convention +- `LIKE`-based `Contains` / `StartsWith` / `EndsWith` — all three supported +- No Couchbase SDK dependency — pure text + parameter builder + +## Limitations + +- No Couchbase SDK dependency: this package only produces `WhereClause` + `Parameters`. Executing the query (via `ICluster.QueryAsync`, `IBucket`, etc.) is entirely the consumer's responsibility. +- Empty `In` list throws `InvalidOperationException` — filter the empty case before building the query. +- `decimal` values are bound as their invariant-culture string representation, not a native numeric parameter. + +## License + +MIT diff --git a/Vali-Flow.NoSql.Couchbase/Translators/CouchbaseFilterTranslator.cs b/Vali-Flow.NoSql.Couchbase/Translators/CouchbaseFilterTranslator.cs new file mode 100644 index 0000000..b1c1398 --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase/Translators/CouchbaseFilterTranslator.cs @@ -0,0 +1,155 @@ +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.NoSql.Couchbase.Models; +using Vali_Flow.NoSql.IR; +using Vali_Flow.NoSql.Translators; + +namespace Vali_Flow.NoSql.Couchbase.Translators; + +/// +/// Translates a IR tree into a Couchbase N1QL (SQL++) +/// . +/// +/// +/// N1QL is plain parameterized text (like SQL), so — unlike Mongo/Elasticsearch/Dynamo — +/// there is no "native" SDK filter object to build; the output is a WHERE clause fragment +/// plus a named-parameter dictionary ($p0, $p1, ...). +/// Identifiers are backtick-quoted (`field`), the same convention N1QL and MySQL share. +/// +public static class CouchbaseFilterTranslator +{ + // The IN values are bound as a single array parameter (not expanded per-value), so the real + // constraint is the max N1QL request size. No official per-element count limit is documented + // by Couchbase — this is a conservative practical cap used as a guardrail. + private const int MaxInValues = 10_000; + + /// + /// Translates the given into a . + /// + /// The root condition node to translate. + /// + /// Optional hook to convert a CLR value into the value bound as an N1QL parameter. + /// Called before the built-in type switch. Return null to fall through to the default conversion. + /// + /// A ready to bind to a N1QL query. + public static CouchbaseFilterExpression Translate(IConditionNode node, Func? customConverter = null, string? tag = null, string? entityType = null) + { + if (node == null) throw new ArgumentNullException(nameof(node)); + + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.NoSql.Couchbase.Translate", tag, entityType); + try + { + var ctx = new TranslationContext(); + var visitor = new CouchbaseVisitor(ctx, customConverter); + var clause = node.Accept(visitor); + return new CouchbaseFilterExpression(clause, ctx.Parameters); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private sealed class CouchbaseVisitor(TranslationContext ctx, Func? customConverter) + : IConditionNodeVisitor + { + public string VisitAnd(AndNode node) => + $"({node.Left.Accept(this)} AND {node.Right.Accept(this)})"; + + public string VisitOr(OrNode node) => + $"({node.Left.Accept(this)} OR {node.Right.Accept(this)})"; + + public string VisitNot(NotNode node) => + $"NOT ({node.Inner.Accept(this)})"; + + public string VisitNull(NullNode node) => + node.Check == NullCheckOp.IsNull + ? $"{Quote(node.Field)} IS NULL" + : $"{Quote(node.Field)} IS NOT NULL"; + + public string VisitEqual(EqualNode node) => + node.IsNegated + ? $"{Quote(node.Field)} <> {ctx.AddValue(ResolveValue(node.Value))}" + : $"{Quote(node.Field)} = {ctx.AddValue(ResolveValue(node.Value))}"; + + public string VisitComparison(ComparisonNode node) => + $"{Quote(node.Field)} {MapComparisonOp(node.Op)} {ctx.AddValue(ResolveValue(node.Value))}"; + + public string VisitLike(LikeNode node) + { + var pattern = node.Op switch + { + LikeOp.Contains => $"%{node.Pattern}%", + LikeOp.StartsWith => $"{node.Pattern}%", + LikeOp.EndsWith => $"%{node.Pattern}", + _ => throw new NotSupportedException($"LikeOp.{node.Op} is not mapped.") + }; + return $"{Quote(node.Field)} LIKE {ctx.AddValue(pattern)}"; + } + + public string VisitIn(InNode node) + { + if (node.Values.Count == 0) + throw new InvalidOperationException( + "IN condition with empty list is not supported in Couchbase N1QL expressions. Filter the empty case before building the query."); + + if (node.Values.Count > MaxInValues) + throw new InvalidOperationException( + $"Couchbase N1QL IN expression supports at most {MaxInValues} values (practical limit, " + + $"bounded by the max N1QL request size); received {node.Values.Count}. " + + "Split the query or batch the values."); + + var values = node.Values.Select(ResolveValue).ToList(); + return $"{Quote(node.Field)} IN {ctx.AddValue(values)}"; + } + + // ── Helpers ────────────────────────────────────────────────────────────────── + + private static string MapComparisonOp(ComparisonOp op) => op switch + { + ComparisonOp.GreaterThan => ">", + ComparisonOp.GreaterThanOrEqual => ">=", + ComparisonOp.LessThan => "<", + ComparisonOp.LessThanOrEqual => "<=", + _ => throw new NotSupportedException($"ComparisonOp.{op} is not mapped.") + }; + + private static string Quote(string field) => $"`{field}`"; + + private object? ResolveValue(object? value) => + ConditionValueResolver.Resolve(value, customConverter, v => v switch + { + null => null, + bool b => b, + string s => s, + int i => i, + long l => l, + double d => d, + float f => (double)f, + // Bound as a native N1QL number, not a string — Couchbase/N1QL has no decimal + // type and does NOT coerce between string and number in comparisons (number < + // string in its collation order), so a string-bound parameter silently matches + // zero rows against a numeric field for every op (=, <>, <, <=, >, >=). + decimal m => m, + Guid g => g.ToString(), + Enum e => Convert.ToInt64(e), + _ => v!.ToString()! + }); + } + + // ── Private translation context (NOT part of public API) ───────────────── + + private sealed class TranslationContext + { + private int _paramCounter; + + public Dictionary Parameters { get; } = new(); + + public string AddValue(object? value) + { + var placeholder = $"$p{_paramCounter++}"; + Parameters[placeholder] = value; + return placeholder; + } + } +} diff --git a/Vali-Flow.NoSql.Couchbase/VF_logo.png b/Vali-Flow.NoSql.Couchbase/VF_logo.png new file mode 100644 index 0000000..1e093e9 Binary files /dev/null and b/Vali-Flow.NoSql.Couchbase/VF_logo.png differ diff --git a/Vali-Flow.NoSql.Couchbase/Vali-Flow.NoSql.Couchbase.csproj b/Vali-Flow.NoSql.Couchbase/Vali-Flow.NoSql.Couchbase.csproj new file mode 100644 index 0000000..2d96429 --- /dev/null +++ b/Vali-Flow.NoSql.Couchbase/Vali-Flow.NoSql.Couchbase.csproj @@ -0,0 +1,47 @@ + + + + net8.0;net9.0 + enable + enable + Vali_Flow.NoSql.Couchbase + Vali-Flow.NoSql.Couchbase + 1.1.0 + Felipe Rafael Montenegro Morriberon + Vali-Flow.NoSql.Couchbase + Couchbase adapter for Vali-Flow.NoSql — translates the provider-agnostic IR tree into a parameterized N1QL (SQL++) WHERE clause fragment. Use .ToCouchbase() on any ValiFlow<T> or Expression<Func<T, bool>>. + Copyright © 2026 - FM. Todos los derechos reservados. + MIT + true + https://vali-flow-docs.netlify.app/docs/adapters/nosql/couchbase/overview + https://github.com/UBF21/vali-flow + git + VF_logo.png + README.md + vali;vali-flow;couchbase;n1ql;sqlpp;filter;nosql;dotnet + v1.1.0 — Fix: decimal values were bound as N1QL string parameters instead of native numbers, making every comparison operator (=, <>, >, >=, <, <=) against a decimal field silently match zero rows (N1QL does not coerce between string and number). Add a MaxInValues cap. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. + true + true + true + embedded + true + snupkg + + + + + True + + + + True + + + + + + + + + + diff --git a/Vali-Flow.NoSql.DynamoDB.Tests/DynamoFilterTranslatorTests.cs b/Vali-Flow.NoSql.DynamoDB.Tests/DynamoFilterTranslatorTests.cs index cc2009f..2aa7e55 100644 --- a/Vali-Flow.NoSql.DynamoDB.Tests/DynamoFilterTranslatorTests.cs +++ b/Vali-Flow.NoSql.DynamoDB.Tests/DynamoFilterTranslatorTests.cs @@ -1,5 +1,7 @@ +using System.Diagnostics; using System.Linq.Expressions; using Amazon.DynamoDBv2.Model; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.NoSql.DynamoDB.Extensions; using Vali_Flow.NoSql.DynamoDB.Models; @@ -11,6 +13,49 @@ namespace Vali_Flow.NoSql.DynamoDB.Tests; public sealed class DynamoFilterTranslatorTests { + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void ToDynamoDB_WithTag_SetsTagAndEntityTypeOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var flow = new ValiFlow().EqualTo(x => x.Name, "Alice"); + + flow.ToDynamoDB(tag: "report-x"); + + captured.Should().NotBeNull(); + captured!.GetTagItem("vali_flow.tag").Should().Be("report-x"); + captured.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestDocument)); + } + + [Fact] + public void Translate_EndsWith_SetsErrorStatusOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var node = new LikeNode("Name", "son", LikeOp.EndsWith); + + Action act = () => DynamoFilterTranslator.Translate(node); + + act.Should().Throw(); + captured.Should().NotBeNull(); + captured!.Status.Should().Be(ActivityStatusCode.Error); + } + // ── Equality ────────────────────────────────────────────────────────────── [Fact] diff --git a/Vali-Flow.NoSql.DynamoDB/Extensions/ValiFlowDynamoExtensions.cs b/Vali-Flow.NoSql.DynamoDB/Extensions/ValiFlowDynamoExtensions.cs index 848d8a7..4c90a8d 100644 --- a/Vali-Flow.NoSql.DynamoDB/Extensions/ValiFlowDynamoExtensions.cs +++ b/Vali-Flow.NoSql.DynamoDB/Extensions/ValiFlowDynamoExtensions.cs @@ -24,6 +24,7 @@ public static class ValiFlowDynamoExtensions /// /// The entity / document type. /// The ValiFlow builder containing the conditions. + /// Optional override to convert a value into an for types the default conversion doesn't handle. /// /// A ready to apply to a ScanRequest or QueryRequest. /// @@ -43,21 +44,21 @@ public static class ValiFlowDynamoExtensions /// }; /// /// - public static DynamoFilterExpression ToDynamoDB(this ValiFlow flow, Func? customConverter = null) where T : class + public static DynamoFilterExpression ToDynamoDB(this ValiFlow flow, Func? customConverter = null, string? tag = null) where T : class { if (flow == null) throw new ArgumentNullException(nameof(flow)); - return DynamoFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter); + return DynamoFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } /// /// Translates a prebuilt into a DynamoDB . /// Use this overload when you already have a compiled expression. /// - public static DynamoFilterExpression ToDynamoDB(this Expression> expression, Func? customConverter = null) + public static DynamoFilterExpression ToDynamoDB(this Expression> expression, Func? customConverter = null, string? tag = null) { if (expression == null) throw new ArgumentNullException(nameof(expression)); - return DynamoFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter); + return DynamoFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } } diff --git a/Vali-Flow.NoSql.DynamoDB/Translators/DynamoFilterTranslator.cs b/Vali-Flow.NoSql.DynamoDB/Translators/DynamoFilterTranslator.cs index 0159e1d..bd39b75 100644 --- a/Vali-Flow.NoSql.DynamoDB/Translators/DynamoFilterTranslator.cs +++ b/Vali-Flow.NoSql.DynamoDB/Translators/DynamoFilterTranslator.cs @@ -1,5 +1,6 @@ using System.Globalization; using Amazon.DynamoDBv2.Model; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.NoSql.DynamoDB.Models; using Vali_Flow.NoSql.IR; using Vali_Flow.NoSql.Translators; @@ -37,14 +38,23 @@ public static class DynamoFilterTranslator /// /// A ready to apply to a ScanRequest or QueryRequest. /// - public static DynamoFilterExpression Translate(IConditionNode node, Func? customConverter = null) + public static DynamoFilterExpression Translate(IConditionNode node, Func? customConverter = null, string? tag = null, string? entityType = null) { if (node == null) throw new ArgumentNullException(nameof(node)); - var ctx = new TranslationContext(); - var visitor = new DynamoVisitor(ctx, customConverter); - var expression = node.Accept(visitor); - return new DynamoFilterExpression(expression, ctx.Names, ctx.Values); + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.NoSql.DynamoDB.Translate", tag, entityType); + try + { + var ctx = new TranslationContext(); + var visitor = new DynamoVisitor(ctx, customConverter); + var expression = node.Accept(visitor); + return new DynamoFilterExpression(expression, ctx.Names, ctx.Values); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } private sealed class DynamoVisitor(TranslationContext ctx, Func? customConverter) diff --git a/Vali-Flow.NoSql.DynamoDB/Vali-Flow.NoSql.DynamoDB.csproj b/Vali-Flow.NoSql.DynamoDB/Vali-Flow.NoSql.DynamoDB.csproj index 1c29d69..d0959b4 100644 --- a/Vali-Flow.NoSql.DynamoDB/Vali-Flow.NoSql.DynamoDB.csproj +++ b/Vali-Flow.NoSql.DynamoDB/Vali-Flow.NoSql.DynamoDB.csproj @@ -6,7 +6,7 @@ enable Vali_Flow.NoSql.DynamoDB Vali-Flow.NoSql.DynamoDB - 1.1.0 + 1.2.0 Felipe Rafael Montenegro Morriberon Vali-Flow.NoSql.DynamoDB AWS DynamoDB adapter for Vali-Flow.NoSql — translates the provider-agnostic IR tree into DynamoDB FilterExpression strings with ExpressionAttributeNames and ExpressionAttributeValues. Use .ToDynamoDB() on any ValiFlow<T> or Expression<Func<T, bool>>. @@ -19,7 +19,7 @@ VF_logo.png README.md vali;vali-flow;dynamodb;aws;filter;nosql;dotnet - v1.1.0 — Enhanced documentation and adapter integration pattern alignment. + v1.2.0 — Add a MaxInValues cap. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing (tag + entityType). No breaking changes. true true true @@ -41,8 +41,8 @@ - + diff --git a/Vali-Flow.NoSql.Elasticsearch.Tests/ElasticsearchFilterTranslatorTests.cs b/Vali-Flow.NoSql.Elasticsearch.Tests/ElasticsearchFilterTranslatorTests.cs index 0870021..300098f 100644 --- a/Vali-Flow.NoSql.Elasticsearch.Tests/ElasticsearchFilterTranslatorTests.cs +++ b/Vali-Flow.NoSql.Elasticsearch.Tests/ElasticsearchFilterTranslatorTests.cs @@ -1,6 +1,8 @@ +using System.Diagnostics; using System.Linq.Expressions; using Elastic.Clients.Elasticsearch; using Elastic.Clients.Elasticsearch.QueryDsl; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.NoSql.Elasticsearch.Extensions; using Vali_Flow.NoSql.Elasticsearch.Translators; @@ -11,6 +13,49 @@ namespace Vali_Flow.NoSql.Elasticsearch.Tests; public sealed class ElasticsearchFilterTranslatorTests { + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void ToElasticsearch_WithTag_SetsTagAndEntityTypeOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var flow = new ValiFlow().EqualTo(x => x.Name, "Alice"); + + flow.ToElasticsearch(tag: "report-x"); + + captured.Should().NotBeNull(); + captured!.GetTagItem("vali_flow.tag").Should().Be("report-x"); + captured.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestDocument)); + } + + [Fact] + public void Translate_UnsupportedComparisonOp_SetsErrorStatusOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var node = new ComparisonNode("Age", 18, (ComparisonOp)999); + + Action act = () => ElasticsearchFilterTranslator.Translate(node); + + act.Should().Throw(); + captured.Should().NotBeNull(); + captured!.Status.Should().Be(ActivityStatusCode.Error); + } + // ── Equality ────────────────────────────────────────────────────────────── [Fact] @@ -313,6 +358,19 @@ public void ToElasticsearch_ValiFlowCombined_ProducesBoolMust() bool_!.Must.Should().HaveCount(2); } + // ── Error handling ─────────────────────────────────────────────────────── + + [Fact] + public void Translate_ComparisonWithNonConvertibleValue_PreservesInnerException() + { + var node = new ComparisonNode("Age", "not-a-number", ComparisonOp.GreaterThan); + + Action act = () => ElasticsearchFilterTranslator.Translate(node); + + act.Should().Throw() + .WithInnerException(); + } + // ── Null guards ─────────────────────────────────────────────────────────── [Fact] @@ -538,6 +596,30 @@ public void ToElasticsearch_TermsWithNullValue_IncludesNullFieldValue() terms.Term.Should().NotBeNull(); } + // ── Límite práctico de terms query (index.max_terms_count) ────────────────── + + [Fact] + public void ToElasticsearch_ListWithMoreThan65536Items_ThrowsInvalidOperationException() + { + var ids = Enumerable.Range(1, 65_537).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => ElasticsearchFilterTranslator.Translate(node); + + act.Should().Throw().WithMessage("*65536*"); + } + + [Fact] + public void ToElasticsearch_ListWithExactly65536Items_DoesNotThrow() + { + var ids = Enumerable.Range(1, 65_536).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => ElasticsearchFilterTranslator.Translate(node); + + act.Should().NotThrow(); + } + // ── Decimal range ───────────────────────────────────────────────────────── [Fact] diff --git a/Vali-Flow.NoSql.Elasticsearch/Extensions/ValiFlowElasticsearchExtensions.cs b/Vali-Flow.NoSql.Elasticsearch/Extensions/ValiFlowElasticsearchExtensions.cs index 7f18e23..fded69c 100644 --- a/Vali-Flow.NoSql.Elasticsearch/Extensions/ValiFlowElasticsearchExtensions.cs +++ b/Vali-Flow.NoSql.Elasticsearch/Extensions/ValiFlowElasticsearchExtensions.cs @@ -38,21 +38,21 @@ public static class ValiFlowElasticsearchExtensions /// var results = await client.SearchAsync<User>(s => s.Query(esFilter)); /// /// - public static Query ToElasticsearch(this ValiFlow flow, Func? customConverter = null) where T : class + public static Query ToElasticsearch(this ValiFlow flow, Func? customConverter = null, string? tag = null) where T : class { if (flow == null) throw new ArgumentNullException(nameof(flow)); - return ElasticsearchFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter); + return ElasticsearchFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } /// /// Translates a prebuilt into an Elasticsearch query. /// Use this overload when you already have a compiled expression. /// - public static Query ToElasticsearch(this Expression> expression, Func? customConverter = null) + public static Query ToElasticsearch(this Expression> expression, Func? customConverter = null, string? tag = null) { if (expression == null) throw new ArgumentNullException(nameof(expression)); - return ElasticsearchFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter); + return ElasticsearchFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } } diff --git a/Vali-Flow.NoSql.Elasticsearch/Translators/ElasticsearchFilterTranslator.cs b/Vali-Flow.NoSql.Elasticsearch/Translators/ElasticsearchFilterTranslator.cs index 5ee55e4..236d210 100644 --- a/Vali-Flow.NoSql.Elasticsearch/Translators/ElasticsearchFilterTranslator.cs +++ b/Vali-Flow.NoSql.Elasticsearch/Translators/ElasticsearchFilterTranslator.cs @@ -1,5 +1,6 @@ using Elastic.Clients.Elasticsearch; using Elastic.Clients.Elasticsearch.QueryDsl; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.NoSql.IR; using Vali_Flow.NoSql.Translators; @@ -17,6 +18,10 @@ namespace Vali_Flow.NoSql.Elasticsearch.Translators; /// public static class ElasticsearchFilterTranslator { + // Elasticsearch's documented server-side limit on terms-query clause count is + // index.max_terms_count, default 65536. https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html + private const int MaxInValues = 65_536; + /// /// Translates the given into an Elasticsearch . /// @@ -35,11 +40,20 @@ public static class ElasticsearchFilterTranslator /// var results = await client.SearchAsync<User>(s => s.Query(esFilter)); /// /// - public static Query Translate(IConditionNode node, Func? customConverter = null) + public static Query Translate(IConditionNode node, Func? customConverter = null, string? tag = null, string? entityType = null) { if (node == null) throw new ArgumentNullException(nameof(node)); - return node.Accept(new ElasticsearchVisitor(customConverter)); + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.NoSql.Elasticsearch.Translate", tag, entityType); + try + { + return node.Accept(new ElasticsearchVisitor(customConverter)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } private sealed class ElasticsearchVisitor(Func? customConverter) : IConditionNodeVisitor @@ -120,6 +134,12 @@ public Query VisitIn(InNode node) MustNot = [Query.MatchAll(new MatchAllQuery())] }); + if (node.Values.Count > MaxInValues) + throw new InvalidOperationException( + $"Elasticsearch terms query supports at most {MaxInValues} values " + + $"(index.max_terms_count server default); received {node.Values.Count}. " + + "Split the query or batch the values."); + return Query.Terms(new TermsQuery { Field = node.Field!, @@ -154,7 +174,7 @@ private static string EscapeWildcard(string pattern) private static double ToDouble(object value) { try { return Convert.ToDouble(value); } - catch { throw new NotSupportedException($"Cannot convert '{value?.GetType().Name}' to double for a range query."); } + catch (Exception ex) { throw new NotSupportedException($"Cannot convert '{value?.GetType().Name}' to double for a range query.", ex); } } private FieldValue ToFieldValue(object? value) => diff --git a/Vali-Flow.NoSql.Elasticsearch/Vali-Flow.NoSql.Elasticsearch.csproj b/Vali-Flow.NoSql.Elasticsearch/Vali-Flow.NoSql.Elasticsearch.csproj index a49b914..ed1dbcf 100644 --- a/Vali-Flow.NoSql.Elasticsearch/Vali-Flow.NoSql.Elasticsearch.csproj +++ b/Vali-Flow.NoSql.Elasticsearch/Vali-Flow.NoSql.Elasticsearch.csproj @@ -6,7 +6,7 @@ enable Vali_Flow.NoSql.Elasticsearch Vali-Flow.NoSql.Elasticsearch - 1.1.0 + 1.2.0 Felipe Rafael Montenegro Morriberon Vali-Flow.NoSql.Elasticsearch Elasticsearch adapter for Vali-Flow.NoSql — translates the provider-agnostic IR tree into Elastic.Clients.Elasticsearch Query objects. Use .ToElasticsearch() on any ValiFlow<T> or Expression<Func<T, bool>>. @@ -24,7 +24,7 @@ embedded true snupkg - v1.1.0 — Enhanced documentation and adapter integration pattern alignment. + v1.2.0 — Fix a swallowed inner exception in ToDouble (now wrapped with context instead of lost). Add a MaxInValues cap (65,536, matching index.max_terms_count). Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. true @@ -41,8 +41,8 @@ - + diff --git a/Vali-Flow.NoSql.Firestore.Tests/Extensions/ValiFlowFirestoreExtensionsTests.cs b/Vali-Flow.NoSql.Firestore.Tests/Extensions/ValiFlowFirestoreExtensionsTests.cs new file mode 100644 index 0000000..614fd13 --- /dev/null +++ b/Vali-Flow.NoSql.Firestore.Tests/Extensions/ValiFlowFirestoreExtensionsTests.cs @@ -0,0 +1,72 @@ +using System.Linq.Expressions; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Firestore.Extensions; +using Vali_Flow.NoSql.Firestore.Tests.Models; + +namespace Vali_Flow.NoSql.Firestore.Tests.Extensions; + +/// Tests for . +public sealed class ValiFlowFirestoreExtensionsTests +{ + [Fact] + public void ToFirestore_ValiFlow_SimpleCondition_ReturnsFilter() + { + var flow = new ValiFlow().EqualTo(x => x.IsActive, true); + + var filter = flow.ToFirestore(); + + filter.Should().NotBeNull(); + } + + [Fact] + public void ToFirestore_ValiFlow_CombinedConditions_ReturnsFilter() + { + var flow = new ValiFlow() + .EqualTo(x => x.IsActive, true) + .GreaterThan(x => x.Age, 18); + + var filter = flow.ToFirestore(); + + filter.Should().NotBeNull(); + } + + [Fact] + public void ToFirestore_NullValiFlow_ThrowsArgumentNullException() + { + ValiFlow? flow = null; + + Action act = () => flow!.ToFirestore(); + + act.Should().Throw().WithParameterName("flow"); + } + + [Fact] + public void ToFirestore_Expression_ReturnsFilter() + { + Expression> expression = x => x.Age > 18; + + var filter = expression.ToFirestore(); + + filter.Should().NotBeNull(); + } + + [Fact] + public void ToFirestore_NullExpression_ThrowsArgumentNullException() + { + Expression>? expression = null; + + Action act = () => expression!.ToFirestore(); + + act.Should().Throw().WithParameterName("expression"); + } + + [Fact] + public void ToFirestore_CustomConverter_IsForwardedToTranslator() + { + var flow = new ValiFlow().EqualTo(x => x.Price, 9.99m); + + var filter = flow.ToFirestore(v => v is decimal d ? (double)d : null); + + filter.Should().NotBeNull(); + } +} diff --git a/Vali-Flow.NoSql.Firestore.Tests/Models/TestDocument.cs b/Vali-Flow.NoSql.Firestore.Tests/Models/TestDocument.cs new file mode 100644 index 0000000..7aac97f --- /dev/null +++ b/Vali-Flow.NoSql.Firestore.Tests/Models/TestDocument.cs @@ -0,0 +1,12 @@ +namespace Vali_Flow.NoSql.Firestore.Tests.Models; + +public sealed class TestDocument +{ + public int Id { get; set; } + public string Name { get; set; } = string.Empty; + public string? Email { get; set; } + public int Age { get; set; } + public decimal Price { get; set; } + public bool IsActive { get; set; } + public string Category { get; set; } = string.Empty; +} diff --git a/Vali-Flow.NoSql.Firestore.Tests/Translators/FirestoreFilterTranslatorTests.cs b/Vali-Flow.NoSql.Firestore.Tests/Translators/FirestoreFilterTranslatorTests.cs new file mode 100644 index 0000000..b65ec15 --- /dev/null +++ b/Vali-Flow.NoSql.Firestore.Tests/Translators/FirestoreFilterTranslatorTests.cs @@ -0,0 +1,185 @@ +using System.Diagnostics; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Firestore.Extensions; +using Vali_Flow.NoSql.Firestore.Tests.Models; +using Vali_Flow.NoSql.Firestore.Translators; +using Vali_Flow.NoSql.IR; + +namespace Vali_Flow.NoSql.Firestore.Tests.Translators; + +public class FirestoreFilterTranslatorTests +{ + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void ToFirestore_WithTag_SetsTagAndEntityTypeOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var flow = new ValiFlow().EqualTo(x => x.Name, "Alice"); + + flow.ToFirestore(tag: "report-x"); + + captured.Should().NotBeNull(); + captured!.GetTagItem("vali_flow.tag").Should().Be("report-x"); + captured.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestDocument)); + } + + [Fact] + public void Translate_LikeNode_SetsErrorStatusOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var node = new LikeNode("Name", "son", LikeOp.Contains); + + Action act = () => FirestoreFilterTranslator.Translate(node); + + act.Should().Throw(); + captured.Should().NotBeNull(); + captured!.Status.Should().Be(ActivityStatusCode.Error); + } + + [Fact] + public void Translate_NullNode_ThrowsArgumentNullException() + { + Action act = () => FirestoreFilterTranslator.Translate(null!); + act.Should().Throw(); + } + + [Fact] + public void VisitEqual_NotNegated_ReturnsEqualToFilter() + { + var node = new EqualNode("Name", "John", isNegated: false); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Fact] + public void VisitEqual_Negated_ReturnsNotEqualToFilter() + { + var node = new EqualNode("Name", "John", isNegated: true); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Theory] + [InlineData(ComparisonOp.GreaterThan)] + [InlineData(ComparisonOp.GreaterThanOrEqual)] + [InlineData(ComparisonOp.LessThan)] + [InlineData(ComparisonOp.LessThanOrEqual)] + public void VisitComparison_SupportedOps_ReturnsFilter(ComparisonOp op) + { + var node = new ComparisonNode("Age", 18, op); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Fact] + public void VisitIn_ReturnsInArrayFilter() + { + var node = new InNode("Category", new List { "a", "b", "c" }); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Fact] + public void VisitNull_IsNull_ReturnsEqualToNullFilter() + { + var node = new NullNode("Email", NullCheckOp.IsNull); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Fact] + public void VisitNull_IsNotNull_ReturnsNotEqualToNullFilter() + { + var node = new NullNode("Email", NullCheckOp.IsNotNull); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Fact] + public void VisitAnd_ReturnsCombinedFilter() + { + var node = new AndNode( + new EqualNode("IsActive", true, isNegated: false), + new ComparisonNode("Age", 18, ComparisonOp.GreaterThan)); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Fact] + public void VisitOr_ReturnsCombinedFilter() + { + var node = new OrNode( + new EqualNode("Category", "a", isNegated: false), + new EqualNode("Category", "b", isNegated: false)); + + var filter = FirestoreFilterTranslator.Translate(node); + + filter.Should().NotBeNull(); + } + + [Theory] + [InlineData(LikeOp.Contains)] + [InlineData(LikeOp.StartsWith)] + [InlineData(LikeOp.EndsWith)] + public void VisitLike_AnyOp_ThrowsNotSupportedException(LikeOp op) + { + var node = new LikeNode("Name", "jo", op, CaseSensitive: true); + + Action act = () => FirestoreFilterTranslator.Translate(node); + + act.Should().Throw() + .WithMessage("*pattern-matching*"); + } + + [Fact] + public void VisitNot_ThrowsNotSupportedException() + { + var node = new NotNode(new EqualNode("IsActive", true, isNegated: false)); + + Action act = () => FirestoreFilterTranslator.Translate(node); + + act.Should().Throw() + .WithMessage("*NOT filter*"); + } + + [Fact] + public void Translate_CustomConverter_IsUsedBeforeFallback() + { + var node = new EqualNode("Price", 42m, isNegated: false); + + var filter = FirestoreFilterTranslator.Translate(node, v => v is decimal d ? (double)d : null); + + filter.Should().NotBeNull(); + } +} diff --git a/Vali-Flow.NoSql.Firestore.Tests/Vali-Flow.NoSql.Firestore.Tests.csproj b/Vali-Flow.NoSql.Firestore.Tests/Vali-Flow.NoSql.Firestore.Tests.csproj new file mode 100644 index 0000000..bb237d6 --- /dev/null +++ b/Vali-Flow.NoSql.Firestore.Tests/Vali-Flow.NoSql.Firestore.Tests.csproj @@ -0,0 +1,29 @@ + + + net9.0 + enable + enable + false + Vali_Flow.NoSql.Firestore.Tests + + + + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + + + + + + + + diff --git a/Vali-Flow.NoSql.Firestore/CHANGELOG.md b/Vali-Flow.NoSql.Firestore/CHANGELOG.md new file mode 100644 index 0000000..7402c45 --- /dev/null +++ b/Vali-Flow.NoSql.Firestore/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog — Vali-Flow.NoSql.Firestore + +All notable changes to this package are documented here. +Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning: [SemVer](https://semver.org/) + +--- + +## [Unreleased] + +--- + +## [1.0.0] — Initial release + +### Added +- `FirestoreFilterTranslator` — translates Vali-Flow IR nodes into a native `Google.Cloud.Firestore.Filter` (Google.Cloud.Firestore 4.4.0) +- `ValiFlowFirestoreExtensions.ToFirestore()` — extension methods on `ValiFlow` and on `Expression>` +- Support for: equality (`EqualTo`/`NotEqualTo`), comparison (`GreaterThan`/`GreaterThanOrEqualTo`/`LessThan`/`LessThanOrEqualTo`), `In`, null checks, `And`/`Or` +- Built-in CLR type mapping (`Enum` → `int`, `DateTime`/`DateTimeOffset` → `Timestamp`, pass-through for primitives) with `customConverter` override hook +- XML documentation on all public types and members + +### Known limitations +- `Contains`/`StartsWith`/`EndsWith` throw `NotSupportedException` — Firestore has no pattern-matching query operator +- `.Not(inner)` throws `NotSupportedException` — the SDK exposes no generic filter negation +- Negated `.In(...)` (`Filter.NotInArray`) not yet reachable — `InNode` has no `IsNegated` flag diff --git a/Vali-Flow.NoSql.Firestore/Extensions/ValiFlowFirestoreExtensions.cs b/Vali-Flow.NoSql.Firestore/Extensions/ValiFlowFirestoreExtensions.cs new file mode 100644 index 0000000..8d9c3a0 --- /dev/null +++ b/Vali-Flow.NoSql.Firestore/Extensions/ValiFlowFirestoreExtensions.cs @@ -0,0 +1,55 @@ +using System.Linq.Expressions; +using Google.Cloud.Firestore; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Extensions; +using Vali_Flow.NoSql.Firestore.Translators; + +namespace Vali_Flow.NoSql.Firestore.Extensions; + +/// +/// Extension methods that add Google Cloud Firestore query-building capabilities to . +/// +/// +/// The returned is the native Firestore SDK type — pass it directly to +/// CollectionReference.Where(filter) or Query.Where(filter). +/// +public static class ValiFlowFirestoreExtensions +{ + /// + /// Translates the conditions built in this instance + /// into a native Firestore . + /// + /// The entity / document type. + /// The ValiFlow builder containing the conditions. + /// + /// Optional override to convert a value into one Firestore accepts, for types the default conversion doesn't handle. + /// + /// A ready to pass to Query.Where(filter). + /// + /// + /// var filter = new ValiFlow<User>() + /// .EqualTo(x => x.IsActive, true) + /// .GreaterThan(x => x.Age, 18); + /// + /// Filter firestoreFilter = filter.ToFirestore(); + /// var snapshot = await collection.Where(firestoreFilter).GetSnapshotAsync(); + /// + /// + public static Filter ToFirestore(this ValiFlow flow, Func? customConverter = null, string? tag = null) where T : class + { + if (flow == null) throw new ArgumentNullException(nameof(flow)); + + return FirestoreFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter, tag, typeof(T).Name); + } + + /// + /// Translates a prebuilt into a native Firestore . + /// Use this overload when you already have a compiled expression. + /// + public static Filter ToFirestore(this Expression> expression, Func? customConverter = null, string? tag = null) + { + if (expression == null) throw new ArgumentNullException(nameof(expression)); + + return FirestoreFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter, tag, typeof(T).Name); + } +} diff --git a/Vali-Flow.NoSql.Firestore/README.md b/Vali-Flow.NoSql.Firestore/README.md new file mode 100644 index 0000000..ad10178 --- /dev/null +++ b/Vali-Flow.NoSql.Firestore/README.md @@ -0,0 +1,45 @@ +# Vali-Flow.NoSql.Firestore + +Google Cloud Firestore adapter that translates `ValiFlow` filters into a native `Google.Cloud.Firestore.Filter`. + +See the [main README](../../README.md) for complete documentation and examples. + +## Installation + +```bash +dotnet add package Vali-Flow.NoSql.Firestore +``` + +## Quick Example + +```csharp +using Vali_Flow.NoSql.Firestore.Extensions; + +var filter = new ValiFlow() + .EqualTo(x => x.IsActive, true) + .GreaterThan(x => x.Age, 18); + +Filter firestoreFilter = filter.ToFirestore(); + +CollectionReference collection = firestoreDb.Collection("users"); +Query query = collection.Where(firestoreFilter); +var snapshot = await query.GetSnapshotAsync(); +``` + +## Features + +- Translates `ValiFlow` expressions to a native `Filter` (the real SDK type, not a wrapper) +- Depends on the official `Google.Cloud.Firestore` 4.4.0 SDK +- Custom value converters for complex types +- `AndNode`/`OrNode`/`EqualNode`/`ComparisonNode`/`InNode`/`NullNode` all supported + +## Limitations + +- **No pattern matching.** `Contains`/`StartsWith`/`EndsWith` (`LikeNode`) throw `NotSupportedException` — Firestore has no LIKE/regex query operator. +- **No generic NOT.** `.Not(inner)` (`NotNode`) throws `NotSupportedException` — the SDK exposes no "negate this filter" composition. Only field-level negation via `.NotEqualTo(...)` (`EqualNode.IsNegated`) is supported. + +See the [full reference](../../docs/en/vali-flow-nosql-firestore.md) for exact exception messages and workarounds. + +## License + +MIT diff --git a/Vali-Flow.NoSql.Firestore/Translators/FirestoreFilterTranslator.cs b/Vali-Flow.NoSql.Firestore/Translators/FirestoreFilterTranslator.cs new file mode 100644 index 0000000..d880e22 --- /dev/null +++ b/Vali-Flow.NoSql.Firestore/Translators/FirestoreFilterTranslator.cs @@ -0,0 +1,104 @@ +using Google.Cloud.Firestore; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.NoSql.IR; +using Vali_Flow.NoSql.Translators; + +namespace Vali_Flow.NoSql.Firestore.Translators; + +/// +/// Translates a IR tree into a native Google Cloud Firestore . +/// +/// +/// The output is accepted directly by Query.Where(filter) — no wrapping needed. +/// +/// Limitations (confirmed against Google.Cloud.Firestore 4.4.0): +/// +/// (Contains/StartsWith/EndsWith) is not supported — Firestore has no +/// pattern-matching/regex query operator. +/// is not supported — the SDK exposes no generic "NOT filter" composition; +/// only field-level negations (NotEqualTo, NotInArray) exist, which are already handled by +/// and would need to be expressed at the node level. +/// +/// +/// +public static class FirestoreFilterTranslator +{ + /// + /// Translates the given into a native Firestore . + /// + /// The root condition node to translate. + /// + /// Optional hook for converting custom CLR types into a value Firestore accepts. + /// Called before the built-in type switch. Return null to fall through to the default conversion. + /// Thread-safe: the converter is scoped to this call only. + /// + /// A ready to pass to Query.Where(filter). + public static Filter Translate(IConditionNode node, Func? customConverter = null, string? tag = null, string? entityType = null) + { + if (node == null) throw new ArgumentNullException(nameof(node)); + + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.NoSql.Firestore.Translate", tag, entityType); + try + { + return node.Accept(new FirestoreVisitor(customConverter)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private sealed class FirestoreVisitor(Func? customConverter) : IConditionNodeVisitor + { + public Filter VisitAnd(AndNode node) => + Filter.And(node.Left.Accept(this), node.Right.Accept(this)); + + public Filter VisitOr(OrNode node) => + Filter.Or(node.Left.Accept(this), node.Right.Accept(this)); + + public Filter VisitNot(NotNode node) => + throw new NotSupportedException( + "Firestore does not support a generic NOT filter over an arbitrary sub-expression. " + + "The SDK only exposes field-level negations (NotEqualTo/NotInArray) via Filter, " + + "which are already handled when the negated node is an EqualNode/InNode directly."); + + public Filter VisitEqual(EqualNode node) => + node.IsNegated + ? Filter.NotEqualTo(node.Field, ToValue(node.Value)) + : Filter.EqualTo(node.Field, ToValue(node.Value)); + + public Filter VisitComparison(ComparisonNode node) => node.Op switch + { + ComparisonOp.GreaterThan => Filter.GreaterThan(node.Field, ToValue(node.Value)), + ComparisonOp.GreaterThanOrEqual => Filter.GreaterThanOrEqualTo(node.Field, ToValue(node.Value)), + ComparisonOp.LessThan => Filter.LessThan(node.Field, ToValue(node.Value)), + ComparisonOp.LessThanOrEqual => Filter.LessThanOrEqualTo(node.Field, ToValue(node.Value)), + _ => throw new NotSupportedException($"ComparisonOp.{node.Op} is not mapped.") + }; + + public Filter VisitLike(LikeNode node) => throw new NotSupportedException( + $"Firestore does not support pattern-matching queries (LikeOp.{node.Op}). " + + "There is no regex/LIKE query operator — filter client-side or use a dedicated search index (e.g. Algolia/Elasticsearch) instead."); + + public Filter VisitIn(InNode node) => + Filter.InArray(node.Field, node.Values.Select(ToValue).ToArray()); + + public Filter VisitNull(NullNode node) => + node.Check == NullCheckOp.IsNull + ? Filter.EqualTo(node.Field, null) + : Filter.NotEqualTo(node.Field, null); + + // ── Helpers ─────────────────────────────────────────────────────────────── + + private object? ToValue(object? value) => + ConditionValueResolver.Resolve(value, customConverter, v => v switch + { + null => null, + Enum e => Convert.ToInt32(e), + DateTimeOffset dto => Timestamp.FromDateTimeOffset(dto), + DateTime dt => Timestamp.FromDateTime(dt.Kind == DateTimeKind.Utc ? dt : dt.ToUniversalTime()), + _ => v + }); + } +} diff --git a/Vali-Flow.NoSql.Firestore/VF_logo.png b/Vali-Flow.NoSql.Firestore/VF_logo.png new file mode 100644 index 0000000..1e093e9 Binary files /dev/null and b/Vali-Flow.NoSql.Firestore/VF_logo.png differ diff --git a/Vali-Flow.NoSql.Firestore/Vali-Flow.NoSql.Firestore.csproj b/Vali-Flow.NoSql.Firestore/Vali-Flow.NoSql.Firestore.csproj new file mode 100644 index 0000000..459237b --- /dev/null +++ b/Vali-Flow.NoSql.Firestore/Vali-Flow.NoSql.Firestore.csproj @@ -0,0 +1,48 @@ + + + + net8.0;net9.0 + enable + enable + Vali_Flow.NoSql.Firestore + Vali-Flow.NoSql.Firestore + 1.1.0 + Felipe Rafael Montenegro Morriberon + Vali-Flow.NoSql.Firestore + Google Cloud Firestore adapter for Vali-Flow.NoSql — translates the provider-agnostic IR tree into a native Google.Cloud.Firestore.Filter. Use .ToFirestore() on any ValiFlow<T> or Expression<Func<T, bool>>. + Copyright © 2026 - FM. Todos los derechos reservados. + MIT + true + https://vali-flow-docs.netlify.app/docs/adapters/nosql/firestore/overview + https://github.com/UBF21/vali-flow + git + VF_logo.png + README.md + vali;vali-flow;firestore;google-cloud;filter;nosql;dotnet + v1.1.0 — Instrument Translate(...) with ValiFlowDiagnostics Activity tracing (tag + entityType). No breaking changes. + true + true + true + embedded + true + snupkg + + + + + True + + + + True + + + + + + + + + + + diff --git a/Vali-Flow.NoSql.MongoDB/CHANGELOG.md b/Vali-Flow.NoSql.MongoDB/CHANGELOG.md index df0ae53..b1e99e4 100644 --- a/Vali-Flow.NoSql.MongoDB/CHANGELOG.md +++ b/Vali-Flow.NoSql.MongoDB/CHANGELOG.md @@ -12,7 +12,11 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning: ## [1.0.0] — Initial release ### Added -- `MongoFilterTranslator` — translates Vali-Flow IR nodes into MongoDB `FilterDefinition` (MongoDB.Driver) -- Support for: equality, comparison, AND/OR/NOT, IN list, LIKE (regex-based), null checks -- `ValiFlowMongoExtensions.ToMongoFilter()` — extension method on `ValiFlow` +- `MongoFilterTranslator` — translates Vali-Flow IR nodes into a MongoDB `BsonDocument` filter (depends only on `MongoDB.Bson`, not the full `MongoDB.Driver`) +- `ValiFlowMongoExtensions.ToMongo()` — extension method on `ValiFlow` and on `Expression>`, with an optional `customConverter` hook for CLR types not handled by the built-in switch +- Support for: equality/inequality, comparison (GT/GTE/LT/LTE), Contains/StartsWith/EndsWith (case-insensitive regex, special characters escaped), IN list, null checks, AND/OR/NOT - XML documentation on all public types and members + +### Fixed +- Closure-captured `null` values now translate to the same `{ field: null }` node as a literal `null` (were previously inconsistent). +- `.In(...)` value lists are now capped at 10,000 entries. See the root [CHANGELOG.md](../CHANGELOG.md) `[Unreleased]` entry for details. diff --git a/Vali-Flow.NoSql.MongoDB/Extensions/ValiFlowMongoExtensions.cs b/Vali-Flow.NoSql.MongoDB/Extensions/ValiFlowMongoExtensions.cs index 6861654..8f130e1 100644 --- a/Vali-Flow.NoSql.MongoDB/Extensions/ValiFlowMongoExtensions.cs +++ b/Vali-Flow.NoSql.MongoDB/Extensions/ValiFlowMongoExtensions.cs @@ -24,6 +24,7 @@ public static class ValiFlowMongoExtensions /// /// The entity / document type. /// The ValiFlow builder containing the conditions. + /// Optional override to convert a value into a for types the default conversion doesn't handle. /// /// A filter ready to pass to Find, CountDocuments, etc. /// @@ -37,21 +38,21 @@ public static class ValiFlowMongoExtensions /// var users = await collection.Find(mongoFilter).ToListAsync(); /// /// - public static BsonDocument ToMongo(this ValiFlow flow, Func? customConverter = null) where T : class + public static BsonDocument ToMongo(this ValiFlow flow, Func? customConverter = null, string? tag = null) where T : class { if (flow == null) throw new ArgumentNullException(nameof(flow)); - return MongoFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter); + return MongoFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } /// /// Translates a prebuilt into a MongoDB filter. /// Use this overload when you already have a compiled expression. /// - public static BsonDocument ToMongo(this Expression> expression, Func? customConverter = null) + public static BsonDocument ToMongo(this Expression> expression, Func? customConverter = null, string? tag = null) { if (expression == null) throw new ArgumentNullException(nameof(expression)); - return MongoFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter); + return MongoFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } } diff --git a/Vali-Flow.NoSql.MongoDB/Translators/MongoFilterTranslator.cs b/Vali-Flow.NoSql.MongoDB/Translators/MongoFilterTranslator.cs index fb8c43b..25f0f8a 100644 --- a/Vali-Flow.NoSql.MongoDB/Translators/MongoFilterTranslator.cs +++ b/Vali-Flow.NoSql.MongoDB/Translators/MongoFilterTranslator.cs @@ -1,5 +1,6 @@ using System.Text.RegularExpressions; using MongoDB.Bson; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.NoSql.IR; using Vali_Flow.NoSql.Translators; @@ -18,6 +19,11 @@ namespace Vali_Flow.NoSql.MongoDB.Translators; /// public static class MongoFilterTranslator { + // MongoDB has no documented hard limit on $in array size — the real constraint is the + // 16MB BSON document limit for the whole query. This is a conservative practical cap to + // prevent abuse/oversized queries, not an official MongoDB limit. + private const int MaxInValues = 10_000; + /// /// Translates the given into a MongoDB filter. /// @@ -37,11 +43,20 @@ public static class MongoFilterTranslator /// var users = await collection.Find(filter).ToListAsync(); /// /// - public static BsonDocument Translate(IConditionNode node, Func? customConverter = null) + public static BsonDocument Translate(IConditionNode node, Func? customConverter = null, string? tag = null, string? entityType = null) { if (node == null) throw new ArgumentNullException(nameof(node)); - return node.Accept(new MongoVisitor(customConverter)); + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.NoSql.MongoDB.Translate", tag, entityType); + try + { + return node.Accept(new MongoVisitor(customConverter)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } private sealed class MongoVisitor(Func? customConverter) : IConditionNodeVisitor @@ -85,10 +100,18 @@ public BsonDocument VisitLike(LikeNode node) => new BsonDocument(node.Field, new BsonDocument("$regex", new BsonRegularExpression(BuildRegexPattern(node.Pattern, node.Op), node.CaseSensitive ? "" : "i"))); - public BsonDocument VisitIn(InNode node) => - new BsonDocument(node.Field, + public BsonDocument VisitIn(InNode node) + { + if (node.Values.Count > MaxInValues) + throw new InvalidOperationException( + $"MongoDB $in filter supports at most {MaxInValues} values (practical limit, " + + $"bounded by the 16MB BSON document size); received {node.Values.Count}. " + + "Split the query or batch the values."); + + return new BsonDocument(node.Field, new BsonDocument("$in", new BsonArray(node.Values.Select(v => ToBsonValue(v))))); + } public BsonDocument VisitNull(NullNode node) => node.Check == NullCheckOp.IsNull diff --git a/Vali-Flow.NoSql.MongoDB/Vali-Flow.NoSql.MongoDB.csproj b/Vali-Flow.NoSql.MongoDB/Vali-Flow.NoSql.MongoDB.csproj index ec8a844..9258ac7 100644 --- a/Vali-Flow.NoSql.MongoDB/Vali-Flow.NoSql.MongoDB.csproj +++ b/Vali-Flow.NoSql.MongoDB/Vali-Flow.NoSql.MongoDB.csproj @@ -6,7 +6,7 @@ enable Vali_Flow.NoSql.MongoDB Vali-Flow.NoSql.MongoDB - 1.1.0 + 1.2.0 Felipe Rafael Montenegro Morriberon Vali-Flow.NoSql.MongoDB MongoDB adapter for Vali-Flow.NoSql — translates the provider-agnostic IR tree into BsonDocument filters using the official MongoDB.Bson library. Use .ToMongo() on any ValiFlow<T> or Expression<Func<T, bool>>. @@ -18,7 +18,7 @@ git VF_logo.png README.md - v1.1.0 — Enhanced documentation and adapter integration pattern alignment. + v1.2.0 — Add a MaxInValues cap (10,000) to InNode translation, a conservative estimate to avoid unbounded $in clauses. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing (tag + entityType). No breaking changes. vali;vali-flow;mongodb;bson;filter;nosql;dotnet true true @@ -41,8 +41,8 @@ - + diff --git a/Vali-Flow.NoSql.Redis.Tests/RedisSearchFilterTranslatorTests.cs b/Vali-Flow.NoSql.Redis.Tests/RedisSearchFilterTranslatorTests.cs index f7005cb..0b9746a 100644 --- a/Vali-Flow.NoSql.Redis.Tests/RedisSearchFilterTranslatorTests.cs +++ b/Vali-Flow.NoSql.Redis.Tests/RedisSearchFilterTranslatorTests.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using System.Linq.Expressions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.NoSql.IR; using Vali_Flow.NoSql.Redis.Extensions; @@ -9,6 +11,49 @@ namespace Vali_Flow.NoSql.Redis.Tests; public sealed class RedisSearchFilterTranslatorTests { + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void ToRedisSearch_WithTag_SetsTagAndEntityTypeOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var flow = new ValiFlow().EqualTo(x => x.Name, "Alice"); + + flow.ToRedisSearch(tag: "report-x"); + + captured.Should().NotBeNull(); + captured!.GetTagItem("vali_flow.tag").Should().Be("report-x"); + captured.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestDocument)); + } + + [Fact] + public void Translate_NullNode_SetsErrorStatusOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var node = new NullNode("DeletedAt", NullCheckOp.IsNull); + + Action act = () => RedisSearchFilterTranslator.Translate(node); + + act.Should().Throw(); + captured.Should().NotBeNull(); + captured!.Status.Should().Be(ActivityStatusCode.Error); + } + // ── Equality ────────────────────────────────────────────────────────────── [Fact] @@ -180,6 +225,42 @@ public void ToRedisSearch_StringEndsWith_ProducesLeadingWildcard() q.Should().Be("@Name:*ce"); } + // ── Pattern match — query-syntax injection guard ──────────────────────────── + + [Fact] + public void ToRedisSearch_ContainsWithParenPipeAt_EscapesSpecialChars() + { + // A pattern containing RediSearch query-syntax characters must not be able to break + // out of this field's scope and inject another clause (e.g. "@other:{admin}"). + Expression> expr = x => x.Name.Contains(")|@other:{admin}"); + + string q = expr.ToRedisSearch(); + + q.Should().Be(@"@Name:*\)\|\@other\:\{admin\}*"); + } + + [Fact] + public void ToRedisSearch_StartsWithSpecialChars_EscapesBeforeTrailingWildcard() + { + Expression> expr = x => x.Name.StartsWith("a-b.c"); + + string q = expr.ToRedisSearch(); + + q.Should().Be(@"@Name:a\-b\.c*"); + } + + [Fact] + public void ToRedisSearch_ContainsLiteralAsterisk_EscapesUserAsteriskButKeepsOwnWildcards() + { + // The '*' the user searches for must be escaped so it stays literal, while the + // wildcard '*' markers this translator adds around it remain unescaped. + Expression> expr = x => x.Name.Contains("a*b"); + + string q = expr.ToRedisSearch(); + + q.Should().Be(@"@Name:*a\*b*"); + } + // ── Membership ──────────────────────────────────────────────────────────── [Fact] @@ -326,6 +407,57 @@ public void CustomValueConverter_WhenReturnsNull_FallsThroughToDefault() q.Should().Be(@"@Name:{""Alice""}"); } + [Fact] + public void CustomValueConverter_UsedForComparisonNode_AppliesToRangeBound() + { + // Regression: ComparisonNode (>, >=, <, <=) used to bypass customConverter entirely + // and go straight to the built-in numeric conversion. + Func converter = v => + v is decimal d ? (d * 100).ToString("0", System.Globalization.CultureInfo.InvariantCulture) : null; + + var node = new ComparisonNode("Price", 9.99m, ComparisonOp.GreaterThan); + string q = RedisSearchFilterTranslator.Translate(node, converter); + + q.Should().Be("@Price:[(999 +inf]"); + } + + [Fact] + public void CustomValueConverter_WhenReturnsNullForComparisonNode_FallsThroughToDefaultNumeric() + { + Func converter = _ => null; + + var node = new ComparisonNode("Age", 18, ComparisonOp.GreaterThanOrEqual); + string q = RedisSearchFilterTranslator.Translate(node, converter); + + q.Should().Be("@Age:[18 +inf]"); + } + + [Fact] + public void CustomValueConverter_UsedForInNode_AppliesToEachNumericValue() + { + // Regression: InNode's numeric branch used to bypass customConverter entirely + // and go straight to the built-in numeric conversion for every value. + Func converter = v => + v is decimal d ? (d * 100).ToString("0", System.Globalization.CultureInfo.InvariantCulture) : null; + + var node = new InNode("Price", new List { 1.5m, 2.5m }); + string q = RedisSearchFilterTranslator.Translate(node, converter); + + q.Should().Be("(@Price:[150 150]|@Price:[250 250])"); + } + + [Fact] + public void CustomValueConverter_UsedForInNode_AppliesToEachTagValue() + { + Func converter = v => + v is string s ? $"TAG_{s}" : null; + + var node = new InNode("Category", new List { "a", "b" }); + string q = RedisSearchFilterTranslator.Translate(node, converter); + + q.Should().Be(@"@Category:{""TAG_a""|""TAG_b""}"); + } + // ── Direct node construction ────────────────────────────────────────────── [Fact] @@ -392,6 +524,30 @@ public void ToRedisSearch_InNodeWithMixedNumericAndString_ThrowsInvalidOperation .WithMessage("*mixed*"); } + // ── Límite práctico de IN (OR'd clauses) ───────────────────────────────── + + [Fact] + public void ToRedisSearch_ListWithMoreThan1000Items_ThrowsInvalidOperationException() + { + var ids = Enumerable.Range(1, 1_001).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => RedisSearchFilterTranslator.Translate(node); + + act.Should().Throw().WithMessage("*1000*"); + } + + [Fact] + public void ToRedisSearch_ListWithExactly1000Items_DoesNotThrow() + { + var ids = Enumerable.Range(1, 1_000).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => RedisSearchFilterTranslator.Translate(node); + + act.Should().NotThrow(); + } + // ── Type Coverage adicional ─────────────────────────────────────────────── [Fact] diff --git a/Vali-Flow.NoSql.Redis/Extensions/ValiFlowRedisSearchExtensions.cs b/Vali-Flow.NoSql.Redis/Extensions/ValiFlowRedisSearchExtensions.cs index 4f09c10..e9d6018 100644 --- a/Vali-Flow.NoSql.Redis/Extensions/ValiFlowRedisSearchExtensions.cs +++ b/Vali-Flow.NoSql.Redis/Extensions/ValiFlowRedisSearchExtensions.cs @@ -35,21 +35,21 @@ public static class ValiFlowRedisSearchExtensions /// var results = db.FT().Search("idx:products", new Query(query)); /// /// - public static string ToRedisSearch(this ValiFlow flow, Func? customConverter = null) where T : class + public static string ToRedisSearch(this ValiFlow flow, Func? customConverter = null, string? tag = null) where T : class { if (flow == null) throw new ArgumentNullException(nameof(flow)); - return RedisSearchFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter); + return RedisSearchFilterTranslator.Translate(flow.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } /// /// Translates a prebuilt into a RediSearch query string. /// Use this overload when you already have a compiled expression. /// - public static string ToRedisSearch(this Expression> expression, Func? customConverter = null) + public static string ToRedisSearch(this Expression> expression, Func? customConverter = null, string? tag = null) { if (expression == null) throw new ArgumentNullException(nameof(expression)); - return RedisSearchFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter); + return RedisSearchFilterTranslator.Translate(expression.ToNoSqlIR(), customConverter, tag, typeof(T).Name); } } diff --git a/Vali-Flow.NoSql.Redis/Translators/RedisSearchFilterTranslator.cs b/Vali-Flow.NoSql.Redis/Translators/RedisSearchFilterTranslator.cs index acdae69..919d01e 100644 --- a/Vali-Flow.NoSql.Redis/Translators/RedisSearchFilterTranslator.cs +++ b/Vali-Flow.NoSql.Redis/Translators/RedisSearchFilterTranslator.cs @@ -1,5 +1,7 @@ using System.Globalization; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.NoSql.IR; +using Vali_Flow.NoSql.Translators; namespace Vali_Flow.NoSql.Redis.Translators; @@ -21,13 +23,23 @@ namespace Vali_Flow.NoSql.Redis.Translators; /// public static class RedisSearchFilterTranslator { + // RediSearch has no documented explicit limit on OR'd terms in a query. This is a + // conservative practical cap: each value expands to a full OR clause in the query string, + // so an unbounded list risks hitting Redis's proto-max-bulk-len and produces unwieldy queries. + private const int MaxInValues = 1_000; + /// /// Translates the given into a RediSearch query string. /// /// The root condition node to translate. /// - /// Optional hook for converting custom CLR types to their Redis tag-value string. - /// Called before the built-in type switch. Return null to fall through to the default conversion. + /// Optional hook for converting custom CLR types to their Redis value string. Applied before the + /// built-in type switch for every value-producing node (Equal, Comparison/range, and IN — both its + /// numeric and tag branches), same evaluation order as the other NoSql providers + /// (): custom first, falls back to + /// the default conversion when it returns null. The string is embedded as a quoted tag value + /// for Equal/IN-tag queries, or unquoted for Comparison/IN-numeric range bounds — return the raw + /// value appropriate to the call site (e.g. a numeric string for a type used in range queries). /// Thread-safe: the converter is scoped to this call only. /// /// @@ -39,13 +51,22 @@ public static class RedisSearchFilterTranslator /// var results = db.FT().Search("idx:products", new Query(query)); /// /// - public static string Translate(IConditionNode node, Func? customConverter = null) + public static string Translate(IConditionNode node, Func? customConverter = null, string? tag = null, string? entityType = null) { if (node == null) throw new ArgumentNullException(nameof(node)); - Validate(node); + using var activity = ValiFlowDiagnostics.StartActivity("Vali-Flow.NoSql.Redis.Translate", tag, entityType); + try + { + Validate(node); - return node.Accept(new RedisVisitor(customConverter)); + return node.Accept(new RedisVisitor(customConverter)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -79,29 +100,50 @@ public string VisitNull(NullNode node) => public string VisitEqual(EqualNode node) => BuildEqualQuery(node.Field, node.Value, node.IsNegated); - public string VisitComparison(ComparisonNode node) => node.Op switch + public string VisitComparison(ComparisonNode node) { - // Exclusive bound uses leading '(' before the number: [(v +inf] - ComparisonOp.GreaterThan => $"@{node.Field}:[({ToNumericString(node.Value)} +inf]", - ComparisonOp.GreaterThanOrEqual => $"@{node.Field}:[{ToNumericString(node.Value)} +inf]", - ComparisonOp.LessThan => $"@{node.Field}:[-inf ({ToNumericString(node.Value)}]", - ComparisonOp.LessThanOrEqual => $"@{node.Field}:[-inf {ToNumericString(node.Value)}]", - _ => throw new NotSupportedException($"ComparisonOp.{node.Op} is not mapped.") - }; + // Custom converter runs first (same order as the other NoSql providers via + // ConditionValueResolver), falling back to the built-in numeric conversion. + var bound = ConditionValueResolver.Resolve(node.Value, customConverter, ToNumericString); - public string VisitLike(LikeNode node) => node.Op switch + return node.Op switch + { + // Exclusive bound uses leading '(' before the number: [(v +inf] + ComparisonOp.GreaterThan => $"@{node.Field}:[({bound} +inf]", + ComparisonOp.GreaterThanOrEqual => $"@{node.Field}:[{bound} +inf]", + ComparisonOp.LessThan => $"@{node.Field}:[-inf ({bound}]", + ComparisonOp.LessThanOrEqual => $"@{node.Field}:[-inf {bound}]", + _ => throw new NotSupportedException($"ComparisonOp.{node.Op} is not mapped.") + }; + } + + public string VisitLike(LikeNode node) { - LikeOp.Contains => $"@{node.Field}:*{node.Pattern}*", - LikeOp.StartsWith => $"@{node.Field}:{node.Pattern}*", - LikeOp.EndsWith => $"@{node.Field}:*{node.Pattern}", - _ => throw new NotSupportedException($"LikeOp.{node.Op} is not mapped.") - }; + // Escape RediSearch query-syntax special characters in the user-supplied pattern + // BEFORE adding our own wildcard '*' markers below — otherwise a pattern containing + // characters like ')', '|', '@' could break out of this field's scope and inject + // arbitrary RediSearch query syntax (e.g. "x) | @other:{admin}"). + string escaped = EscapeTextTerm(node.Pattern); + return node.Op switch + { + LikeOp.Contains => $"@{node.Field}:*{escaped}*", + LikeOp.StartsWith => $"@{node.Field}:{escaped}*", + LikeOp.EndsWith => $"@{node.Field}:*{escaped}", + _ => throw new NotSupportedException($"LikeOp.{node.Op} is not mapped.") + }; + } public string VisitIn(InNode node) { // Empty IN → always false (negate match-all) if (node.Values.Count == 0) return "(-*)"; + if (node.Values.Count > MaxInValues) + throw new InvalidOperationException( + $"RediSearch IN query supports at most {MaxInValues} values (practical limit — " + + $"each value expands to a full OR clause in the query string); received {node.Values.Count}. " + + "Split the query or batch the values."); + if (node.Values.Any(v => v == null)) throw new InvalidOperationException( "IN condition with null values is not supported in Redis Search. Remove null values before building the query."); @@ -119,7 +161,12 @@ public string VisitIn(InNode node) if (allNumeric) { // OR'd range queries: (@field:[v1 v1]|@field:[v2 v2]|...) - var parts = node.Values.Select(v => $"@{node.Field}:[{ToNumericString(v!)} {ToNumericString(v!)}]"); + // Custom converter first, same order as Equal/Comparison, falls back to numeric. + var parts = node.Values.Select(v => + { + var num = ConditionValueResolver.Resolve(v!, customConverter, ToNumericString); + return $"@{node.Field}:[{num} {num}]"; + }); return $"({string.Join("|", parts)})"; } @@ -132,17 +179,16 @@ public string VisitIn(InNode node) private string BuildEqualQuery(string field, object value, bool negated) { - // OCP: custom converter takes priority over built-in type detection - if (customConverter != null) + // Custom converter takes priority over built-in type detection (OCP), + // same evaluation order as every other NoSql provider via ConditionValueResolver: + // custom first, fall back to the default conversion only when it returns null. + var custom = customConverter?.Invoke(value); + if (custom != null) { - var custom = customConverter(value); - if (custom != null) - { - var customTag = $"\"{EscapeTagValue(custom)}\""; - return negated - ? $"-@{field}:{{{customTag}}}" - : $"@{field}:{{{customTag}}}"; - } + var customTag = $"\"{EscapeTagValue(custom)}\""; + return negated + ? $"-@{field}:{{{customTag}}}" + : $"@{field}:{{{customTag}}}"; } if (IsNumericOrBool(value)) @@ -154,37 +200,29 @@ private string BuildEqualQuery(string field, object value, bool negated) } // String / other → quoted tag query (DIALECT 2). - // Converter already returned null above — pass null to avoid double-invocation (O1 fix). - var tag = BuildTagValue(value, null); + // Custom converter already ran above and returned null — build the default tag directly. + var tag = $"\"{EscapeTagValue(DefaultTagString(value))}\""; return negated ? $"-@{field}:{{{tag}}}" : $"@{field}:{{{tag}}}"; } - private string BuildTagValue(object? value, Func? converter = null) - { - var conv = converter ?? customConverter; - if (conv != null) - { - var custom = conv(value); - if (custom != null) return $"\"{EscapeTagValue(custom)}\""; - } + private string BuildTagValue(object? value) => + $"\"{EscapeTagValue(ConditionValueResolver.Resolve(value, customConverter, DefaultTagString))}\""; - var str = value switch - { - null => string.Empty, - bool b => b ? "true" : "false", - string s => s, - Enum e => e.ToString(), - _ => value.ToString() ?? string.Empty - }; - return $"\"{EscapeTagValue(str)}\""; - } + private static string DefaultTagString(object? value) => value switch + { + null => string.Empty, + bool b => b ? "true" : "false", + string s => s, + Enum e => e.ToString()!, + _ => value.ToString() ?? string.Empty + }; private static bool IsNumericOrBool(object? value) => value is int or long or double or float or decimal or bool; - private static string ToNumericString(object value) => value switch + private static string ToNumericString(object? value) => value switch { bool b => b ? "1" : "0", int i => i.ToString(CultureInfo.InvariantCulture), @@ -198,6 +236,24 @@ private static bool IsNumericOrBool(object? value) => // Escape \ and " inside DIALECT 2 quoted tag values private static string EscapeTagValue(string value) => value.Replace("\\", "\\\\").Replace("\"", "\\\""); + + // RediSearch query-syntax special characters that must be backslash-escaped when they + // appear inside an unquoted text term (used for Contains/StartsWith/EndsWith wildcards). + // Backslash is escaped first so escaping the others doesn't double-escape it. + private static readonly char[] TextTermSpecialChars = + { '\\', ',', '.', '<', '>', '{', '}', '[', ']', '"', '\'', ':', ';', '!', + '@', '#', '$', '%', '^', '&', '*', '(', ')', '-', '+', '=', '~', '|' }; + + private static string EscapeTextTerm(string value) + { + var sb = new System.Text.StringBuilder(value.Length); + foreach (char c in value) + { + if (Array.IndexOf(TextTermSpecialChars, c) >= 0) sb.Append('\\'); + sb.Append(c); + } + return sb.ToString(); + } } } diff --git a/Vali-Flow.NoSql.Redis/Vali-Flow.NoSql.Redis.csproj b/Vali-Flow.NoSql.Redis/Vali-Flow.NoSql.Redis.csproj index 7dbc1a4..c723110 100644 --- a/Vali-Flow.NoSql.Redis/Vali-Flow.NoSql.Redis.csproj +++ b/Vali-Flow.NoSql.Redis/Vali-Flow.NoSql.Redis.csproj @@ -6,7 +6,7 @@ enable Vali_Flow.NoSql.Redis Vali-Flow.NoSql.Redis - 1.1.0 + 1.2.0 Felipe Rafael Montenegro Morriberon Vali-Flow.NoSql.Redis Redis RediSearch adapter for Vali-Flow.NoSql — translates the provider-agnostic IR tree into RediSearch query strings compatible with NRedisStack (DIALECT 2). Use .ToRedisSearch() on any ValiFlow<T> or Expression<Func<T, bool>>. @@ -19,7 +19,7 @@ VF_logo.png README.md vali;vali-flow;redis;redisearch;query;filter;nosql;dotnet - v1.1.0 — Enhanced documentation and adapter integration pattern alignment. + v1.2.0 — Security fix: escape RediSearch query-syntax special characters in LIKE patterns before adding wildcards, closing a query-injection vector (e.g. a pattern containing ')' or '|' could previously break out of the field's scope). Fix customConverter not being applied in VisitComparison/numeric VisitIn. Add a MaxInValues cap (1,000). Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. true true true @@ -41,8 +41,8 @@ - + diff --git a/Vali-Flow.NoSql.Tests/ExpressionToIRVisitorTests.cs b/Vali-Flow.NoSql.Tests/ExpressionToIRVisitorTests.cs index 37cd94a..291f28d 100644 --- a/Vali-Flow.NoSql.Tests/ExpressionToIRVisitorTests.cs +++ b/Vali-Flow.NoSql.Tests/ExpressionToIRVisitorTests.cs @@ -89,6 +89,32 @@ public void ToNoSqlIR_NotEqualNull_ReturnsIsNotNullNode() node.Check.Should().Be(NullCheckOp.IsNotNull); } + [Fact] + public void ToNoSqlIR_EqualNullVariable_ReturnsIsNullNode() + { + string? email = null; + Expression> expr = x => x.Email == email; + + var ir = expr.ToNoSqlIR(); + + var node = ir.Should().BeOfType().Subject; + node.Field.Should().Be("Email"); + node.Check.Should().Be(NullCheckOp.IsNull); + } + + [Fact] + public void ToNoSqlIR_NotEqualNullVariable_ReturnsIsNotNullNode() + { + string? email = null; + Expression> expr = x => x.Email != email; + + var ir = expr.ToNoSqlIR(); + + var node = ir.Should().BeOfType().Subject; + node.Field.Should().Be("Email"); + node.Check.Should().Be(NullCheckOp.IsNotNull); + } + // ── Comparison ──────────────────────────────────────────────────────────── [Fact] diff --git a/Vali-Flow.NoSql.Tests/MongoFilterTranslatorTests.cs b/Vali-Flow.NoSql.Tests/MongoFilterTranslatorTests.cs index cf0bd36..2b27e33 100644 --- a/Vali-Flow.NoSql.Tests/MongoFilterTranslatorTests.cs +++ b/Vali-Flow.NoSql.Tests/MongoFilterTranslatorTests.cs @@ -1,5 +1,7 @@ +using System.Diagnostics; using System.Linq.Expressions; using MongoDB.Bson; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.NoSql.IR; using Vali_Flow.NoSql.MongoDB.Extensions; @@ -10,6 +12,49 @@ namespace Vali_Flow.NoSql.Tests; public sealed class MongoFilterTranslatorTests { + private static ActivityListener AttachListener() + { + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData + }; + ActivitySource.AddActivityListener(listener); + return listener; + } + + [Fact] + public void ToMongo_WithTag_SetsTagAndEntityTypeOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var flow = new ValiFlow().EqualTo(x => x.Name, "Alice"); + + flow.ToMongo(tag: "report-x"); + + captured.Should().NotBeNull(); + captured!.GetTagItem("vali_flow.tag").Should().Be("report-x"); + captured.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestDocument)); + } + + [Fact] + public void Translate_UnsupportedComparisonOp_SetsErrorStatusOnActivity() + { + using var listener = AttachListener(); + Activity? captured = null; + listener.ActivityStopped = a => captured = a; + + var node = new ComparisonNode("Age", 18, (ComparisonOp)999); + + Action act = () => MongoFilterTranslator.Translate(node); + + act.Should().Throw(); + captured.Should().NotBeNull(); + captured!.Status.Should().Be(ActivityStatusCode.Error); + } + // ── Equality ────────────────────────────────────────────────────────────── [Fact] @@ -253,6 +298,26 @@ public void Translate_NullNode_ThrowsArgumentNullException() act.Should().Throw(); } + [Fact] + public void ToMongo_NullFlow_ThrowsArgumentNullException() + { + ValiFlow? flow = null; + + Action act = () => flow!.ToMongo(); + + act.Should().Throw(); + } + + [Fact] + public void ToMongo_NullExpression_ThrowsArgumentNullException() + { + Expression>? expr = null; + + Action act = () => expr!.ToMongo(); + + act.Should().Throw(); + } + // ── OCP — CustomValueConverter ──────────────────────────────────────────── [Fact] @@ -387,6 +452,30 @@ public void ToMongo_InNodeWithNullValue_HandlesNullInBsonArray() arr[1].Should().Be(BsonNull.Value); } + // ── Límite práctico de $in ─────────────────────────────────────────────── + + [Fact] + public void ToMongo_ListWithMoreThan10000Items_ThrowsInvalidOperationException() + { + var ids = Enumerable.Range(1, 10_001).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => MongoFilterTranslator.Translate(node); + + act.Should().Throw().WithMessage("*10000*"); + } + + [Fact] + public void ToMongo_ListWithExactly10000Items_DoesNotThrow() + { + var ids = Enumerable.Range(1, 10_000).Cast().ToList(); + var node = new InNode("Id", ids); + + Action act = () => MongoFilterTranslator.Translate(node); + + act.Should().NotThrow(); + } + // ── Lógica anidada ──────────────────────────────────────────────────────── [Fact] diff --git a/Vali-Flow.NoSql/Translators/ExpressionToIRVisitor.cs b/Vali-Flow.NoSql/Translators/ExpressionToIRVisitor.cs index f3860eb..69e7a27 100644 --- a/Vali-Flow.NoSql/Translators/ExpressionToIRVisitor.cs +++ b/Vali-Flow.NoSql/Translators/ExpressionToIRVisitor.cs @@ -119,6 +119,15 @@ private static IConditionNode TranslateComparison(BinaryExpression node) string fieldName = GetMemberName(columnExpr); object? value = EvaluateExpression(valueExpr); + // A captured variable/constant that evaluates to null (e.g. `x.Email == someNullVar`) + // carries the same semantics as a literal `== null` — route it to NullNode instead of + // letting EqualNode's null guard throw an unrelated ArgumentNullException. + if (value is null && effectiveType is ExpressionType.Equal or ExpressionType.NotEqual) + { + return new NullNode(fieldName, + effectiveType == ExpressionType.Equal ? NullCheckOp.IsNull : NullCheckOp.IsNotNull); + } + return effectiveType switch { ExpressionType.Equal => new EqualNode(fieldName, value!, false), diff --git a/Vali-Flow.NoSql/Vali-Flow.NoSql.csproj b/Vali-Flow.NoSql/Vali-Flow.NoSql.csproj index 8406aeb..4528c57 100644 --- a/Vali-Flow.NoSql/Vali-Flow.NoSql.csproj +++ b/Vali-Flow.NoSql/Vali-Flow.NoSql.csproj @@ -6,7 +6,7 @@ enable Vali_Flow.NoSql Vali-Flow.NoSql - 1.1.0 + 1.1.1 Felipe Rafael Montenegro Morriberon Provider-agnostic NoSql IR for Vali-Flow.Core — converts expression trees to a neutral condition node tree that can be translated to MongoDB, Elasticsearch, or any document store. MIT @@ -22,13 +22,13 @@ embedded true snupkg - v1.1.0 — Enhanced documentation and contracts alignment, improved adapter integration pattern. + v1.1.1 — Fix: x.Field == nullVariable (a closure-captured null) now translates to NullNode like the x.Field == null literal path instead of throwing ArgumentNullException. No breaking changes. - + diff --git a/Vali-Flow.Sql.Tests/AssemblyInfo.cs b/Vali-Flow.Sql.Tests/AssemblyInfo.cs new file mode 100644 index 0000000..b4f34e7 --- /dev/null +++ b/Vali-Flow.Sql.Tests/AssemblyInfo.cs @@ -0,0 +1,10 @@ +using Xunit; + +// Several test classes in this project assert on System.Diagnostics.Activity captured via a +// process-wide ActivityListener on ValiFlowDiagnostics.Source (see e.g. SqlDeleteBuilderTests' +// AttachScopedListener/GetOwn helpers). Parenting each test's activities under a private root and +// filtering by ParentId reduces -- but does not eliminate -- cross-test collisions under xUnit's +// default test-class-level parallelism: it was still observed intermittently failing with "Sequence +// contains no matching element" across the 6 SQL builder test classes. Disabling parallelization for +// this assembly removes the race at its source; the full suite still runs in well under a second. +[assembly: CollectionBehavior(DisableTestParallelization = true)] diff --git a/Vali-Flow.Sql.Tests/Builder/SqlDeleteBuilderTests.cs b/Vali-Flow.Sql.Tests/Builder/SqlDeleteBuilderTests.cs index f21c151..a031f32 100644 --- a/Vali-Flow.Sql.Tests/Builder/SqlDeleteBuilderTests.cs +++ b/Vali-Flow.Sql.Tests/Builder/SqlDeleteBuilderTests.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using FluentAssertions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.Sql.Builder; using Vali_Flow.Sql.Dialects; @@ -11,6 +13,27 @@ public sealed class SqlDeleteBuilderTests { private static readonly ISqlDialect Sql = new SqlServerDialect(); private static readonly ISqlDialect Pg = new PostgreSqlDialect(); + + // Parents every captured activity under a private root so concurrently running tests (xunit + // parallelizes test classes by default) can never pollute this test's capture, even though they + // share the same process-wide ValiFlowDiagnostics.Source. + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root) + => captured.Single(a => a.ParentId == root.Id); private static readonly ISqlDialect My = new MySqlDialect(); // ── Basic DELETE ────────────────────────────────────────────────────────── @@ -27,6 +50,14 @@ public void NoWhere_GeneratesDeleteWithoutWhere() result.Parameters.Should().BeEmpty(); } + [Fact] + public void From_UnsafeTableName_ThrowsArgumentException() + { + var act = () => new SqlDeleteBuilder(Sql).From("Users]; DROP TABLE Users;--"); + + act.Should().Throw().WithParameterName("tableName"); + } + // ── WHERE variants ──────────────────────────────────────────────────────── [Fact] @@ -92,6 +123,44 @@ public void Where_BothPredicateAndBuilder_AreAnded() result.Sql.Should().Contain("AND"); } + [Fact] + public void Where_LambdaExpression_CalledTwice_ThrowsInvalidOperationException() + { + // Previously this silently overwrote the first predicate with the second one + // with no error — inconsistent with the SqlWhereBuilder overload (Where(SqlWhereBuilder)), + // which already guards against being set twice. + var builder = new SqlDeleteBuilder(Sql) + .From("Users") + .Where(x => x.Age < 18); + + builder.Invoking(b => b.Where(x => x.Age > 65)) + .Should().Throw(); + } + + [Fact] + public void Where_ValiFlow_CalledTwice_ThrowsInvalidOperationException() + { + var filter1 = new ValiFlow().EqualTo(x => x.Department, "Sales"); + var filter2 = new ValiFlow().EqualTo(x => x.Department, "IT"); + var builder = new SqlDeleteBuilder(Sql) + .From("Users") + .Where(filter1); + + builder.Invoking(b => b.Where(filter2)) + .Should().Throw(); + } + + [Fact] + public void Where_SqlWhereBuilder_CalledTwice_ThrowsInvalidOperationException() + { + var builder = new SqlDeleteBuilder(Sql) + .From("Users") + .Where(w => w.EqualTo(x => x.Id, 1)); + + builder.Invoking(b => b.Where(w => w.EqualTo(x => x.Id, 2))) + .Should().Throw(); + } + // ── Table + schema ──────────────────────────────────────────────────────── [Fact] @@ -230,4 +299,40 @@ public void Constructor_NullDialect_ThrowsArgumentNullException() var act = () => new SqlDeleteBuilder(null!); act.Should().Throw(); } + + // ── Observability ───────────────────────────────────────────────────────── + + [Fact] + public void Build_WithTag_RecordsActivityWithTagAndEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + new SqlDeleteBuilder(Sql) + .From("Users") + .AllowDeleteAll() + .Tag("Delete all users") + .Build(); + + var seen = GetOwn(captured, root); + seen.GetTagItem("vali_flow.tag").Should().Be("Delete all users"); + seen.GetTagItem("vali_flow.entity_type").Should().Be("TestUser"); + seen.GetTagItem("vali_flow.has_where").Should().Be(false); + seen.Status.Should().Be(ActivityStatusCode.Unset); + } + + [Fact] + public void Build_WithoutWhereOrAllowDeleteAll_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + // No Where() and no AllowDeleteAll() triggers the existing safety guard in Build(). + var act = () => new SqlDeleteBuilder(Sql).From("Users").Build(); + + act.Should().Throw(); + GetOwn(captured, root).Status.Should().Be(ActivityStatusCode.Error); + } } diff --git a/Vali-Flow.Sql.Tests/Builder/SqlInsertBuilderTests.cs b/Vali-Flow.Sql.Tests/Builder/SqlInsertBuilderTests.cs index ba51c2a..73512f4 100644 --- a/Vali-Flow.Sql.Tests/Builder/SqlInsertBuilderTests.cs +++ b/Vali-Flow.Sql.Tests/Builder/SqlInsertBuilderTests.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using FluentAssertions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Sql.Builder; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Tests.Models; @@ -12,6 +14,27 @@ public sealed class SqlInsertBuilderTests private static readonly ISqlDialect Pg = new PostgreSqlDialect(); private static readonly ISqlDialect My = new MySqlDialect(); + // Parents every captured activity under a private root so concurrently running tests (xunit + // parallelizes test classes by default) can never pollute this test's capture, even though they + // share the same process-wide ValiFlowDiagnostics.Source. + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root) + => captured.Single(a => a.ParentId == root.Id); + // ── Basic INSERT ────────────────────────────────────────────────────────── [Fact] @@ -26,6 +49,22 @@ public void SingleSet_GeneratesInsertWithOneColumn() result.Parameters["pi0"].Should().Be("Alice"); } + [Fact] + public void Into_UnsafeTableName_ThrowsArgumentException() + { + var act = () => new SqlInsertBuilder(Sql).Into("Users]; DROP TABLE Users;--"); + + act.Should().Throw().WithParameterName("tableName"); + } + + [Fact] + public void Into_UnsafeSchema_ThrowsArgumentException() + { + var act = () => new SqlInsertBuilder(Sql).Into("Users", "dbo]; DROP TABLE Users;--"); + + act.Should().Throw().WithParameterName("schema"); + } + [Fact] public void MultipleSet_GeneratesCorrectColumnAndParamOrder() { @@ -379,6 +418,37 @@ public void InsertIgnore_SqlServer_ThrowsInvalidOperationException() .WithMessage("*SqlServer*"); } + [Fact] + public void OrIgnore_MySql_ThrowsInvalidOperationException() + { + // MySQL does not support the SQLite-only "INSERT OR IGNORE INTO" syntax. + // MySqlDialect.InsertConflictPrefix is "IGNORE" (used for its own InsertIgnore() keyword), + // which previously made the OrIgnore() guard pass incorrectly and emit invalid SQL + // ("INSERT OR IGNORE INTO ..." instead of "INSERT IGNORE INTO ..."). + var builder = new SqlInsertBuilder(My) + .Into("Users") + .Set(x => x.Name, "Alice"); + + builder.Invoking(b => b.OrIgnore()) + .Should().Throw() + .WithMessage("*MySQL*"); + } + + [Fact] + public void OrReplace_PostgreSql_ThrowsInvalidOperationException() + { + // PostgreSQL does not support the SQLite-only "INSERT OR REPLACE INTO" syntax either. + // PostgreSqlDialect.SupportsOnConflict is true (for ON CONFLICT DO UPDATE/NOTHING), + // which previously made the OrReplace() guard pass incorrectly. + var builder = new SqlInsertBuilder(Pg) + .Into("Users") + .Set(x => x.Name, "Alice"); + + builder.Invoking(b => b.OrReplace()) + .Should().Throw() + .WithMessage("*PostgreSQL*"); + } + // ── INSERT … SELECT ─────────────────────────────────────────────────────── [Fact] @@ -484,6 +554,25 @@ public void SelectFrom_AndSet_ThrowsInvalidOperationException() .Should().Throw(); } + [Fact] + public void Set_AfterSelectFrom_ThrowsInvalidOperationException() + { + // Reverse of SelectFrom_AndSet_ThrowsInvalidOperationException: calling Set() after + // SelectFrom() was previously NOT guarded. Build() always checks _selectQuery first and + // routes into BuildInsertSelect(), silently discarding whatever was passed to Set() with + // no error raised to the caller — an asymmetric, order-dependent validation gap. + var select = new SqlQueryBuilder(Sql) + .From("Archive") + .Build(); + + var builder = new SqlInsertBuilder(Sql) + .Into("Users") + .SelectFrom(select); + + builder.Invoking(b => b.Set(x => x.Name, "Alice")) + .Should().Throw(); + } + [Fact] public void SelectFrom_NullQuery_ThrowsArgumentNullException() { @@ -516,4 +605,110 @@ public void SelectFrom_MySql_UsesBackticks() result.Sql.Should().StartWith("INSERT INTO `Users`"); result.Sql.Should().Contain("(`Name`)"); } + + // ── SetAllFrom ──────────────────────────────────────────────────────────── + + [Fact] + public void SetAllFrom_MapsAllPublicProperties() + { + var entity = new TestUser + { + Id = 1, + Name = "Alice", + Email = "alice@test.com", + Age = 30, + IsActive = true, + CreatedAt = new DateTime(2024, 1, 1), + Department = "Eng", + Salary = 1000m, + Status = 1, + Counter = 0, + NameBackup = "AliceBackup", + UpdatedAt = new DateTime(2024, 1, 2) + }; + + var result = new SqlInsertBuilder(Sql) + .Into("Users") + .SetAllFrom(entity) + .Build(); + + result.Sql.Should().Contain("[Id]").And.Contain("[Name]").And.Contain("[Email]"); + result.Parameters.Values.Should().Contain("Alice"); + result.Parameters.Values.Should().Contain("alice@test.com"); + result.Parameters.Values.Should().Contain(30); + result.Parameters.Values.Should().Contain(true); + } + + [Fact] + public void SetAllFrom_WithExclusions_SkipsExcludedColumns() + { + var entity = new TestUser { Id = 1, Name = "Bob", Email = "bob@test.com" }; + + var result = new SqlInsertBuilder(Sql) + .Into("Users") + .SetAllFrom(entity, x => x.Id, x => x.CreatedAt, x => x.UpdatedAt) + .Build(); + + result.Sql.Should().NotContain("[Id]"); + result.Sql.Should().NotContain("[CreatedAt]"); + result.Sql.Should().NotContain("[UpdatedAt]"); + result.Sql.Should().Contain("[Name]"); + } + + [Fact] + public void SetAllFrom_NullPropertyValue_StoresDbNull() + { + var entity = new TestUser { Id = 1, Name = "Carl", Email = null! }; + + var result = new SqlInsertBuilder(Sql) + .Into("Users") + .SetAllFrom(entity) + .Build(); + + result.Parameters.Values.Should().Contain(DBNull.Value); + } + + [Fact] + public void SetAllFrom_NullEntity_ThrowsArgumentNullException() + { + var builder = new SqlInsertBuilder(Sql).Into("Users"); + + builder.Invoking(b => b.SetAllFrom(null!)) + .Should().Throw().WithParameterName("entity"); + } + + // ── Observability ───────────────────────────────────────────────────────── + + [Fact] + public void Build_WithTag_RecordsActivityWithTagAndEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + new SqlInsertBuilder(Sql) + .Into("Users") + .Set(x => x.Name, "Alice") + .Tag("Insert new user") + .Build(); + + var seen = GetOwn(captured, root); + seen.GetTagItem("vali_flow.tag").Should().Be("Insert new user"); + seen.GetTagItem("vali_flow.entity_type").Should().Be("TestUser"); + seen.Status.Should().Be(ActivityStatusCode.Unset); + } + + [Fact] + public void Build_WhenValidationThrows_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + // No Set() calls at all triggers the existing "at least one column" guard in Build(). + var act = () => new SqlInsertBuilder(Sql).Into("Users").Build(); + + act.Should().Throw(); + GetOwn(captured, root).Status.Should().Be(ActivityStatusCode.Error); + } } diff --git a/Vali-Flow.Sql.Tests/Builder/SqlMergeBuilderTests.cs b/Vali-Flow.Sql.Tests/Builder/SqlMergeBuilderTests.cs index 45248ec..1c9793d 100644 --- a/Vali-Flow.Sql.Tests/Builder/SqlMergeBuilderTests.cs +++ b/Vali-Flow.Sql.Tests/Builder/SqlMergeBuilderTests.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using FluentAssertions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Sql.Builder; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Tests.Models; @@ -10,6 +12,27 @@ public sealed class SqlMergeBuilderTests { private static readonly ISqlDialect Sql = new SqlServerDialect(); + // Parents every captured activity under a private root so concurrently running tests (xunit + // parallelizes test classes by default) can never pollute this test's capture, even though they + // share the same process-wide ValiFlowDiagnostics.Source. + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root) + => captured.Single(a => a.ParentId == root.Id); + // ── Basic MERGE ─────────────────────────────────────────────────────────── [Fact] @@ -32,6 +55,24 @@ public void Build_BasicMerge_GeneratesMergeStatement() result.Sql.Should().EndWith(";"); } + [Fact] + public void Into_UnsafeTableName_ThrowsArgumentException() + { + var act = () => new SqlMergeBuilder(Sql).Into("Users]; DROP TABLE Users;--"); + + act.Should().Throw().WithParameterName("tableName"); + } + + [Fact] + public void Using_UnsafeSourceTable_ThrowsArgumentException() + { + var act = () => new SqlMergeBuilder(Sql) + .Into("Users") + .Using("StagingUsers]; DROP TABLE StagingUsers;--"); + + act.Should().Throw().WithParameterName("sourceTable"); + } + // ── WHEN MATCHED UPDATE ─────────────────────────────────────────────────── [Fact] @@ -82,6 +123,37 @@ public void Build_WhenNotMatchedBySourceDelete_GeneratesDeleteClause() .Using("StagingUsers") .On(t => t.Id, s => s.Id) .WhenNotMatchedBySourceDelete() + .AllowDeleteUnmatched() + .Build(); + + result.Sql.Should().Contain("WHEN NOT MATCHED BY SOURCE THEN DELETE"); + } + + // ── AllowDeleteUnmatched guard ───────────────────────────────────────────── + + [Fact] + public void Build_WhenNotMatchedBySourceDeleteWithoutGuard_ThrowsInvalidOperationException() + { + var builder = new SqlMergeBuilder(Sql) + .Into("Users") + .Using("StagingUsers") + .On(t => t.Id, s => s.Id) + .WhenNotMatchedBySourceDelete(); + + builder.Invoking(b => b.Build()) + .Should().Throw() + .WithMessage("*AllowDeleteUnmatched()*"); + } + + [Fact] + public void Build_WhenNotMatchedBySourceDeleteWithGuard_GeneratesDeleteClause() + { + var result = new SqlMergeBuilder(Sql) + .Into("Users") + .Using("StagingUsers") + .On(t => t.Id, s => s.Id) + .WhenNotMatchedBySourceDelete() + .AllowDeleteUnmatched() .Build(); result.Sql.Should().Contain("WHEN NOT MATCHED BY SOURCE THEN DELETE"); @@ -131,6 +203,7 @@ public void Build_WithSchema_GeneratesSchemaQualifiedTarget() .Using("StagingUsers") .On(t => t.Id, s => s.Id) .WhenNotMatchedBySourceDelete() + .AllowDeleteUnmatched() .Build(); result.Sql.Should().Contain("MERGE INTO [dbo].[Users] AS target"); @@ -147,6 +220,7 @@ public void Build_WithoutInto_ThrowsInvalidOperationException() .Using("StagingUsers") .On(t => t.Id, s => s.Id) .WhenNotMatchedBySourceDelete() + .AllowDeleteUnmatched() .Build(); act.Should().Throw() @@ -161,7 +235,8 @@ public void Build_NonSqlServerDialect_ThrowsInvalidOperationException() var builder = new SqlMergeBuilder(new PostgreSqlDialect()) .Using("StagingUsers") .On(t => t.Id, s => s.Id) - .WhenNotMatchedBySourceDelete(); + .WhenNotMatchedBySourceDelete() + .AllowDeleteUnmatched(); builder.Invoking(b => b.Build()) .Should().Throw() @@ -176,7 +251,8 @@ public void Build_NoOnCondition_ThrowsInvalidOperationException() var builder = new SqlMergeBuilder(Sql) .Into("Users") .Using("StagingUsers") - .WhenNotMatchedBySourceDelete(); + .WhenNotMatchedBySourceDelete() + .AllowDeleteUnmatched(); builder.Invoking(b => b.Build()) .Should().Throw() @@ -208,6 +284,7 @@ public void Tag_PrependsSqlComment() .Using("StagingUsers") .On(t => t.Id, s => s.Id) .WhenNotMatchedBySourceDelete() + .AllowDeleteUnmatched() .Tag("Sync staging to production") .Build(); @@ -246,4 +323,47 @@ public void Build_WithOracleDialect_DoesNotUseAsAlias() result.Sql.Should().Contain("target"); result.Sql.Should().Contain("MERGE INTO"); } + + // ── Observability ───────────────────────────────────────────────────────── + + [Fact] + public void Build_WithTag_RecordsActivityWithTagAndTargetEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + new SqlMergeBuilder(Sql) + .Into("Users") + .Using("StagingUsers") + .On(t => t.Id, s => s.Id) + .WhenMatchedUpdate(b => b.MatchedSetColumn(t => t.Name, s => s.Name)) + .Tag("Sync users") + .Build(); + + var seen = GetOwn(captured, root); + seen.GetTagItem("vali_flow.tag").Should().Be("Sync users"); + seen.GetTagItem("vali_flow.entity_type").Should().Be("TestUser"); + seen.GetTagItem("vali_flow.has_delete_unmatched").Should().Be(false); + seen.Status.Should().Be(ActivityStatusCode.Unset); + } + + [Fact] + public void Build_DeleteUnmatchedWithoutAllow_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + // WhenNotMatchedBySourceDelete() without AllowDeleteUnmatched() triggers the existing safety guard. + var act = () => new SqlMergeBuilder(Sql) + .Into("Users") + .Using("StagingUsers") + .On(t => t.Id, s => s.Id) + .WhenNotMatchedBySourceDelete() + .Build(); + + act.Should().Throw(); + GetOwn(captured, root).Status.Should().Be(ActivityStatusCode.Error); + } } diff --git a/Vali-Flow.Sql.Tests/Builder/SqlTruncateBuilderTests.cs b/Vali-Flow.Sql.Tests/Builder/SqlTruncateBuilderTests.cs index 435ee6d..5a79aec 100644 --- a/Vali-Flow.Sql.Tests/Builder/SqlTruncateBuilderTests.cs +++ b/Vali-Flow.Sql.Tests/Builder/SqlTruncateBuilderTests.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using FluentAssertions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Sql.Builder; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Tests.Models; @@ -13,6 +15,27 @@ public sealed class SqlTruncateBuilderTests private static readonly ISqlDialect My = new MySqlDialect(); private static readonly ISqlDialect Sqlite = new SqliteDialect(); + // Parents every captured activity under a private root so concurrently running tests (xunit + // parallelizes test classes by default) can never pollute this test's capture, even though they + // share the same process-wide ValiFlowDiagnostics.Source. + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root) + => captured.Single(a => a.ParentId == root.Id); + // ── Basic TRUNCATE ──────────────────────────────────────────────────────── [Fact] @@ -25,6 +48,14 @@ public void Table_SqlServer_GeneratesTruncate() result.Sql.Should().Be("TRUNCATE TABLE [Users]"); } + [Fact] + public void Table_UnsafeTableName_ThrowsArgumentException() + { + var act = () => new SqlTruncateBuilder(Sql).Table("Users]; DROP TABLE Users;--"); + + act.Should().Throw().WithParameterName("tableName"); + } + [Fact] public void Table_WithSchema_GeneratesSchemaQualified() { @@ -119,4 +150,38 @@ public void Constructor_NullDialect_ThrowsArgumentNullException() var act = () => new SqlTruncateBuilder(null!); act.Should().Throw(); } + + // ── Observability ───────────────────────────────────────────────────────── + + [Fact] + public void Build_WithTag_RecordsActivityWithTagAndEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + new SqlTruncateBuilder(Sql) + .Table("Users") + .Tag("Truncate users") + .Build(); + + var seen = GetOwn(captured, root); + seen.GetTagItem("vali_flow.tag").Should().Be("Truncate users"); + seen.GetTagItem("vali_flow.entity_type").Should().Be("TestUser"); + seen.Status.Should().Be(ActivityStatusCode.Unset); + } + + [Fact] + public void Build_UnsupportedDialect_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + // SQLite does not support TRUNCATE TABLE, triggering the existing guard in Build(). + var act = () => new SqlTruncateBuilder(Sqlite).Table("Users").Build(); + + act.Should().Throw(); + GetOwn(captured, root).Status.Should().Be(ActivityStatusCode.Error); + } } diff --git a/Vali-Flow.Sql.Tests/Builder/SqlUpdateBuilderTests.cs b/Vali-Flow.Sql.Tests/Builder/SqlUpdateBuilderTests.cs index 38b2fc0..6a33ae3 100644 --- a/Vali-Flow.Sql.Tests/Builder/SqlUpdateBuilderTests.cs +++ b/Vali-Flow.Sql.Tests/Builder/SqlUpdateBuilderTests.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using FluentAssertions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.Sql.Builder; using Vali_Flow.Sql.Dialects; @@ -13,6 +15,27 @@ public sealed class SqlUpdateBuilderTests private static readonly ISqlDialect Pg = new PostgreSqlDialect(); private static readonly ISqlDialect My = new MySqlDialect(); + // Parents every captured activity under a private root so concurrently running tests (xunit + // parallelizes test classes by default) can never pollute this test's capture, even though they + // share the same process-wide ValiFlowDiagnostics.Source. + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root) + => captured.Single(a => a.ParentId == root.Id); + // ── Basic UPDATE ────────────────────────────────────────────────────────── [Fact] @@ -28,6 +51,24 @@ public void SingleSet_NoWhere_GeneratesUpdateWithoutWhere() result.Parameters["pu0"].Should().Be("Alice"); } + [Fact] + public void Table_UnsafeTableName_ThrowsArgumentException() + { + var act = () => new SqlUpdateBuilder(Sql).Table("Users]; DROP TABLE Users;--"); + + act.Should().Throw().WithParameterName("tableName"); + } + + [Fact] + public void FromTable_UnsafeSourceTable_ThrowsArgumentException() + { + var builder = new SqlUpdateBuilder(Sql).Table("Users"); + + var act = () => builder.FromTable("Orders]; DROP TABLE Orders;--"); + + act.Should().Throw().WithParameterName("sourceTable"); + } + [Fact] public void MultipleSet_GeneratesCorrectSetList() { @@ -110,6 +151,47 @@ public void Where_ValiFlow_AppendsWhereClause() result.Sql.Should().Contain("[IsActive]"); } + [Fact] + public void Where_SqlWhereBuilder_CalledTwice_ThrowsInvalidOperationException() + { + var builder = new SqlUpdateBuilder(Sql) + .Table("Users") + .Set(x => x.Name, "A") + .Where(w => w.EqualTo(x => x.Id, 1)); + + builder.Invoking(b => b.Where(w => w.EqualTo(x => x.Id, 2))) + .Should().Throw(); + } + + [Fact] + public void Where_LambdaExpression_CalledTwice_ThrowsInvalidOperationException() + { + // Previously this silently overwrote the first predicate with the second one + // with no error — inconsistent with the SqlWhereBuilder overload above, which + // already guards against being set twice. + var builder = new SqlUpdateBuilder(Sql) + .Table("Users") + .Set(x => x.Name, "A") + .Where(x => x.Age > 18); + + builder.Invoking(b => b.Where(x => x.Age < 65)) + .Should().Throw(); + } + + [Fact] + public void Where_ValiFlow_CalledTwice_ThrowsInvalidOperationException() + { + var filter1 = new ValiFlow().EqualTo(x => x.IsActive, true); + var filter2 = new ValiFlow().EqualTo(x => x.IsActive, false); + var builder = new SqlUpdateBuilder(Sql) + .Table("Users") + .Set(x => x.Name, "A") + .Where(filter1); + + builder.Invoking(b => b.Where(filter2)) + .Should().Throw(); + } + // ── Table + schema ──────────────────────────────────────────────────────── [Fact] @@ -442,4 +524,105 @@ public void JoinOn_EmptyJoinType_ThrowsArgumentException() builder.Invoking(b => b.JoinOn("", "condition")) .Should().Throw(); } + + // ── SetAllFrom ──────────────────────────────────────────────────────────── + + [Fact] + public void SetAllFrom_MapsAllPropertiesExceptPrimaryKey() + { + var entity = new TestUser + { + Id = 42, + Name = "Alice", + Email = "alice@test.com", + Age = 30, + IsActive = true + }; + + var result = new SqlUpdateBuilder(Sql) + .Table("Users") + .SetAllFrom(entity, x => x.Id) + .AllowUpdateAll() + .Build(); + + result.Sql.Should().NotContain("[Id] ="); + result.Sql.Should().Contain("[Name] ="); + result.Parameters.Values.Should().Contain("Alice"); + result.Parameters.Values.Should().Contain(30); + } + + [Fact] + public void SetAllFrom_WithWhere_CombinesWithPkFilter() + { + var entity = new TestUser { Id = 7, Name = "Bob" }; + + var result = new SqlUpdateBuilder(Sql) + .Table("Users") + .SetAllFrom(entity, x => x.Id) + .Where(w => w.EqualTo(x => x.Id, entity.Id)) + .Build(); + + result.Sql.Should().Contain("WHERE [Id] = @pw0"); + result.Parameters["pw0"].Should().Be(7); + } + + [Fact] + public void SetAllFrom_NullPropertyValue_StoresDbNull() + { + var entity = new TestUser { Id = 1, Name = "Carl", Email = null! }; + + var result = new SqlUpdateBuilder(Sql) + .Table("Users") + .SetAllFrom(entity, x => x.Id) + .AllowUpdateAll() + .Build(); + + result.Parameters.Values.Should().Contain(DBNull.Value); + } + + [Fact] + public void SetAllFrom_NullEntity_ThrowsArgumentNullException() + { + var builder = new SqlUpdateBuilder(Sql).Table("Users"); + + builder.Invoking(b => b.SetAllFrom(null!)) + .Should().Throw().WithParameterName("entity"); + } + + // ── Observability ───────────────────────────────────────────────────────── + + [Fact] + public void Build_WithTag_RecordsActivityWithTagAndEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + new SqlUpdateBuilder(Sql) + .Table("Users") + .Set(x => x.Name, "Bob") + .AllowUpdateAll() + .Tag("Update user name") + .Build(); + + var seen = GetOwn(captured, root); + seen.GetTagItem("vali_flow.tag").Should().Be("Update user name"); + seen.GetTagItem("vali_flow.entity_type").Should().Be("TestUser"); + seen.GetTagItem("vali_flow.has_where").Should().Be(false); + seen.Status.Should().Be(ActivityStatusCode.Unset); + } + + [Fact] + public void Build_WithoutWhereOrAllowUpdateAll_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + // No Where() and no AllowUpdateAll() triggers the existing safety guard in Build(). + var act = () => new SqlUpdateBuilder(Sql).Table("Users").Set(x => x.Name, "Bob").Build(); + + act.Should().Throw(); + GetOwn(captured, root).Status.Should().Be(ActivityStatusCode.Error); + } } diff --git a/Vali-Flow.Sql.Tests/SqlIdentifierGuardTests.cs b/Vali-Flow.Sql.Tests/SqlIdentifierGuardTests.cs new file mode 100644 index 0000000..d405e15 --- /dev/null +++ b/Vali-Flow.Sql.Tests/SqlIdentifierGuardTests.cs @@ -0,0 +1,71 @@ +using FluentAssertions; +using Vali_Flow.Sql.Builder; +using Xunit; + +namespace Vali_Flow.Sql.Tests; + +/// +/// Tests for — the SQL injection guard for table/schema/type names. +/// +public sealed class SqlIdentifierGuardTests +{ + [Theory] + [InlineData("Users")] + [InlineData("_users")] + [InlineData("Users_2024")] + [InlineData("dbo")] + public void EnsureValidIdentifier_ValidName_ReturnsSameValue(string name) + { + var result = SqlIdentifierGuard.EnsureValidIdentifier(name, "tableName"); + + result.Should().Be(name); + } + + [Theory] + [InlineData("Users]; DROP TABLE Users;--")] + [InlineData("Users\"; DROP TABLE Users;--")] + [InlineData("Users`; DROP TABLE Users;--")] + [InlineData("Users WHERE 1=1")] + [InlineData("Users; SELECT 1")] + [InlineData("1Users")] + [InlineData("Us ers")] + public void EnsureValidIdentifier_UnsafeName_ThrowsArgumentException(string name) + { + var act = () => SqlIdentifierGuard.EnsureValidIdentifier(name, "tableName"); + + act.Should().Throw().WithParameterName("tableName"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public void EnsureValidIdentifier_EmptyName_ThrowsArgumentException(string? name) + { + var act = () => SqlIdentifierGuard.EnsureValidIdentifier(name!, "tableName"); + + act.Should().Throw().WithParameterName("tableName"); + } + + [Theory] + [InlineData("INT")] + [InlineData("VARCHAR(50)")] + [InlineData("DECIMAL(18,2)")] + [InlineData("NVARCHAR(MAX)")] + public void EnsureValidTypeName_ValidType_ReturnsSameValue(string typeName) + { + var result = SqlIdentifierGuard.EnsureValidTypeName(typeName, "typeName"); + + result.Should().Be(typeName); + } + + [Theory] + [InlineData("INT); DROP TABLE Users;--")] + [InlineData("VARCHAR(50); SELECT 1")] + public void EnsureValidTypeName_UnsafeType_ThrowsArgumentException(string typeName) + { + var act = () => SqlIdentifierGuard.EnsureValidTypeName(typeName, "typeName"); + + act.Should().Throw().WithParameterName("typeName"); + } +} diff --git a/Vali-Flow.Sql.Tests/SqlQueryBuilderTests.cs b/Vali-Flow.Sql.Tests/SqlQueryBuilderTests.cs index ab1cd14..4749112 100644 --- a/Vali-Flow.Sql.Tests/SqlQueryBuilderTests.cs +++ b/Vali-Flow.Sql.Tests/SqlQueryBuilderTests.cs @@ -1,5 +1,7 @@ +using System.Diagnostics; using System.Linq.Expressions; using FluentAssertions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Sql.Builder; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Tests.Models; @@ -25,6 +27,24 @@ public void Build_SelectStar_WhenNoColumnsSpecified() result.Parameters.Should().BeEmpty(); } + [Theory] + [InlineData("Users]; DROP TABLE Users;--")] + [InlineData("Users WHERE 1=1")] + public void From_UnsafeTableName_ThrowsArgumentException(string tableName) + { + var act = () => Sql().From(tableName); + + act.Should().Throw().WithParameterName("tableName"); + } + + [Fact] + public void From_UnsafeSchema_ThrowsArgumentException() + { + var act = () => Sql().From("Users", "dbo]; DROP TABLE Users;--"); + + act.Should().Throw().WithParameterName("schema"); + } + [Fact] public void Build_SelectSpecificColumns() { @@ -1413,6 +1433,14 @@ public void SelectCast_GeneratesCastInSelect() result.Sql.Should().Contain("CAST([Age] AS FLOAT) AS [AgeFloat]"); } + [Fact] + public void SelectCast_UnsafeTypeName_ThrowsArgumentException() + { + var act = () => Sql().From("Users").SelectCast(x => x.Age, "INT); DROP TABLE Users;--", "AgeInt"); + + act.Should().Throw().WithParameterName("typeName"); + } + [Fact] public void SelectConcat_SqlServer_UsesPlus() { @@ -1787,4 +1815,56 @@ public void JoinSubquery_EmptyAlias_ThrowsArgumentException() builder.Invoking(b => b.InnerJoinSubquery(subquery, " ", "ON 1=1")) .Should().Throw(); } + + // ── Observability ───────────────────────────────────────────────────────── + + // Parents every captured activity under a private root so concurrently running tests (xunit + // parallelizes test classes by default) can never pollute this test's capture, even though they + // share the same process-wide ValiFlowDiagnostics.Source. + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root) + => captured.Single(a => a.ParentId == root.Id); + + [Fact] + public void Build_WithTag_RecordsActivityWithTagAndEntityType() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + Sql().From("Users").Tag("Get active users").Build(); + + var seen = GetOwn(captured, root); + seen.GetTagItem("vali_flow.tag").Should().Be("Get active users"); + seen.GetTagItem("vali_flow.entity_type").Should().Be("TestUser"); + seen.Status.Should().Be(ActivityStatusCode.Unset); + } + + [Fact] + public void Build_WhenValidationThrows_RecordsErrorStatus() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + // Skip without Take/OrderBy triggers the existing pagination validation guard in Build(). + var act = () => Sql().From("Users").Skip(10).Build(); + + act.Should().Throw(); + GetOwn(captured, root).Status.Should().Be(ActivityStatusCode.Error); + } } diff --git a/Vali-Flow.Sql.Tests/ValiFlowSqlExtensionsTests.cs b/Vali-Flow.Sql.Tests/ValiFlowSqlExtensionsTests.cs index 86e0d58..557afa9 100644 --- a/Vali-Flow.Sql.Tests/ValiFlowSqlExtensionsTests.cs +++ b/Vali-Flow.Sql.Tests/ValiFlowSqlExtensionsTests.cs @@ -94,6 +94,13 @@ public void ToSqlCount_NullDialect_ThrowsArgumentNull() act.Should().Throw().WithParameterName("dialect"); } + [Fact] + public void ToSqlCount_UnsafeTableName_ThrowsArgumentException() + { + var act = () => ((ValiFlow?)null).ToSqlCount(SqlServer, "Users]; DROP TABLE Users;--"); + act.Should().Throw().WithParameterName("tableName"); + } + // ── ToSql (ValiFlowQuery overload) ───────────────────────────────────── [Fact] @@ -166,6 +173,13 @@ public void ToSqlCount_ValiFlowQuery_NullDialect_ThrowsArgumentNull() act.Should().Throw().WithParameterName("dialect"); } + [Fact] + public void ToSqlCount_ValiFlowQuery_UnsafeTableName_ThrowsArgumentException() + { + var act = () => ((ValiFlowQuery?)null).ToSqlCount(SqlServer, "Users]; DROP TABLE Users;--"); + act.Should().Throw().WithParameterName("tableName"); + } + [Fact] public void ToSqlCount_ValiFlowQuery_PostgreSQL_UsesDoubleQuotes() { diff --git a/Vali-Flow.Sql/Builder/SqlDeleteBuilder.cs b/Vali-Flow.Sql/Builder/SqlDeleteBuilder.cs index 1ed4f1a..2232cec 100644 --- a/Vali-Flow.Sql/Builder/SqlDeleteBuilder.cs +++ b/Vali-Flow.Sql/Builder/SqlDeleteBuilder.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using System.Linq.Expressions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Models; @@ -44,10 +46,8 @@ public SqlDeleteBuilder(ISqlDialect dialect) /// Sets the target table name and optional schema. public SqlDeleteBuilder From(string tableName, string? schema = null) { - if (string.IsNullOrWhiteSpace(tableName)) - throw new ArgumentException("Table name cannot be null or empty.", nameof(tableName)); - _tableName = tableName; - _schema = schema; + _tableName = SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName)); + _schema = schema == null ? null : SqlIdentifierGuard.EnsureValidIdentifier(schema, nameof(schema)); return this; } @@ -78,7 +78,11 @@ public SqlDeleteBuilder Where(Action> configure) /// both conditions are combined with AND in the final SQL. public SqlDeleteBuilder Where(Expression> predicate) { - _wherePredicate = predicate ?? throw new ArgumentNullException(nameof(predicate)); + if (predicate == null) throw new ArgumentNullException(nameof(predicate)); + if (_wherePredicate != null) + throw new InvalidOperationException( + "Where predicate already set. Combine conditions within a single expression (e.g. with &&)."); + _wherePredicate = predicate; return this; } @@ -86,8 +90,7 @@ public SqlDeleteBuilder Where(Expression> predicate) public SqlDeleteBuilder Where(ValiFlow filter) { if (filter == null) throw new ArgumentNullException(nameof(filter)); - _wherePredicate = filter.Build(); - return this; + return Where(filter.Build()); } // ── OUTPUT / RETURNING ──────────────────────────────────────────────────── @@ -141,6 +144,24 @@ public SqlDeleteBuilder Tag(string description) /// Assembles and returns the final . public SqlQueryResult Build() + { + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.Sql.SqlDeleteBuilder.Build", tag: _tag, entityType: typeof(T).Name); + try + { + SqlQueryResult result = BuildCore(); + bool hasWhere = _wherePredicate != null || _whereBuilder != null; + activity?.SetTag("vali_flow.has_where", hasWhere); + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private SqlQueryResult BuildCore() { bool hasWhere = _wherePredicate != null || _whereBuilder != null; if (!hasWhere && !_allowDeleteAll) diff --git a/Vali-Flow.Sql/Builder/SqlIdentifierGuard.cs b/Vali-Flow.Sql/Builder/SqlIdentifierGuard.cs new file mode 100644 index 0000000..1f5ca94 --- /dev/null +++ b/Vali-Flow.Sql/Builder/SqlIdentifierGuard.cs @@ -0,0 +1,43 @@ +using System.Text.RegularExpressions; + +namespace Vali_Flow.Sql.Builder; + +/// +/// Validates raw SQL identifiers (table/schema names) and type names before they are interpolated +/// into generated SQL. Table/schema/type names cannot be parameterized like regular values +/// (there is no @param equivalent for an identifier), so this is the only line of defense +/// against SQL injection when a consumer builds these strings from untrusted input. +/// +internal static class SqlIdentifierGuard +{ + private static readonly Regex IdentifierPattern = new("^[A-Za-z_][A-Za-z0-9_]*$", RegexOptions.Compiled); + + // Allows simple type names (INT, VARCHAR) and parameterized ones (DECIMAL(18,2), NVARCHAR(MAX)). + private static readonly Regex TypeNamePattern = + new(@"^[A-Za-z_][A-Za-z0-9_]*(\([A-Za-z0-9_,\s]+\))?$", RegexOptions.Compiled); + + /// Validates a table or schema name. Throws if it contains anything beyond letters, digits and underscores. + public static string EnsureValidIdentifier(string name, string paramName) + { + if (string.IsNullOrWhiteSpace(name)) + throw new ArgumentException("Identifier cannot be empty.", paramName); + if (!IdentifierPattern.IsMatch(name)) + throw new ArgumentException( + $"'{name}' is not a valid SQL identifier. Only letters, digits and underscores are allowed " + + "(table/schema names cannot be parameterized, so unsafe characters are rejected to prevent SQL injection).", + paramName); + return name; + } + + /// Validates a SQL type name used in a CAST expression (e.g. "VARCHAR(50)", "DECIMAL(18,2)"). + public static string EnsureValidTypeName(string typeName, string paramName) + { + if (string.IsNullOrWhiteSpace(typeName)) + throw new ArgumentException("Type name cannot be empty.", paramName); + if (!TypeNamePattern.IsMatch(typeName)) + throw new ArgumentException( + $"'{typeName}' is not a valid SQL type name (expected something like 'INT' or 'VARCHAR(50)').", + paramName); + return typeName; + } +} diff --git a/Vali-Flow.Sql/Builder/SqlInsertBuilder.cs b/Vali-Flow.Sql/Builder/SqlInsertBuilder.cs index 2860252..867ec89 100644 --- a/Vali-Flow.Sql/Builder/SqlInsertBuilder.cs +++ b/Vali-Flow.Sql/Builder/SqlInsertBuilder.cs @@ -1,5 +1,8 @@ +using System.Diagnostics; using System.Linq.Expressions; +using System.Reflection; using System.Text.RegularExpressions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Models; @@ -74,10 +77,8 @@ public SqlInsertBuilder(ISqlDialect dialect) /// Sets the target table name and optional schema. public SqlInsertBuilder Into(string tableName, string? schema = null) { - if (string.IsNullOrWhiteSpace(tableName)) - throw new ArgumentException("Table name cannot be null or empty.", nameof(tableName)); - _tableName = tableName; - _schema = schema; + _tableName = SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName)); + _schema = schema == null ? null : SqlIdentifierGuard.EnsureValidIdentifier(schema, nameof(schema)); return this; } @@ -90,10 +91,55 @@ public SqlInsertBuilder Into(string tableName, string? schema = null) public SqlInsertBuilder Set(Expression> column, TValue value) { if (column == null) throw new ArgumentNullException(nameof(column)); + if (_selectQuery != null) + throw new InvalidOperationException( + "Cannot combine Set() with SelectFrom(). Use one or the other."); CurrentRow.Add((ExpressionHelper.GetMemberName(column), value)); return this; } + /// + /// Maps every public readable instance property of to a + /// call for the current row, reading each value from + /// via reflection. Properties listed in + /// (typically the primary key) are skipped. + /// + /// + /// Limitations: only public instance properties are considered; indexers + /// (this[int]) and non-public properties are always skipped. Collection/complex + /// navigation properties are mapped like any other property (their raw value is passed to + /// as-is) — this method does not attempt to flatten or serialize them. + /// + public SqlInsertBuilder SetAllFrom(T entity, params Expression>[] exclude) + { + if (entity == null) throw new ArgumentNullException(nameof(entity)); + + var excluded = exclude != null + ? new HashSet(exclude.Select(ExpressionHelper.GetMemberName)) + : new HashSet(); + + foreach (var prop in typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance)) + { + if (prop.GetIndexParameters().Length > 0) continue; + if (!prop.CanRead) continue; + if (excluded.Contains(prop.Name)) continue; + + var value = prop.GetValue(entity); + var parameter = Expression.Parameter(typeof(T), "x"); + var lambda = Expression.Lambda( + typeof(Func<,>).MakeGenericType(typeof(T), prop.PropertyType), + Expression.Property(parameter, prop), + parameter); + + var setMethod = typeof(SqlInsertBuilder) + .GetMethod(nameof(Set))! + .MakeGenericMethod(prop.PropertyType); + setMethod.Invoke(this, new object?[] { lambda, value }); + } + + return this; + } + // ── Multi-row ───────────────────────────────────────────────────────────── /// @@ -169,7 +215,12 @@ public SqlInsertBuilder Tag(string description) /// public SqlInsertBuilder OrIgnore() { - if (!_dialect.SupportsOnConflict && string.IsNullOrEmpty(_dialect.InsertConflictPrefix)) + // "INSERT OR IGNORE INTO" is SQLite-only syntax. MySqlDialect.InsertConflictPrefix is + // "IGNORE" (used for its own InsertIgnore() → "INSERT IGNORE INTO" keyword, unrelated + // to this method) and PostgreSqlDialect.SupportsOnConflict is true (for ON CONFLICT + // DO NOTHING/UPDATE, unrelated to this method too). Checking either of those alone + // previously let MySQL and PostgreSQL through here and produced invalid SQL. + if (_dialect.DialectName != "SQLite") throw new InvalidOperationException( $"OrIgnore() is not supported by dialect '{_dialect.DialectName}'."); _orIgnore = true; @@ -182,7 +233,8 @@ public SqlInsertBuilder OrIgnore() /// public SqlInsertBuilder OrReplace() { - if (!_dialect.SupportsOnConflict && string.IsNullOrEmpty(_dialect.InsertConflictPrefix)) + // Same reasoning as OrIgnore(): "INSERT OR REPLACE INTO" is SQLite-only syntax. + if (_dialect.DialectName != "SQLite") throw new InvalidOperationException( $"OrReplace() is not supported by dialect '{_dialect.DialectName}'."); _orReplace = true; @@ -347,6 +399,24 @@ public SqlInsertBuilder Columns(params Expression>[] columns) /// Assembles and returns the final . public SqlQueryResult Build() + { + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.Sql.SqlInsertBuilder.Build", tag: _tag, entityType: typeof(T).Name); + try + { + SqlQueryResult result = BuildCore(); + activity?.SetTag("vali_flow.row_count", _rows.Count); + activity?.SetTag("vali_flow.is_insert_select", _selectQuery != null); + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private SqlQueryResult BuildCore() { _paramIndex = 0; diff --git a/Vali-Flow.Sql/Builder/SqlMergeBuilder.cs b/Vali-Flow.Sql/Builder/SqlMergeBuilder.cs index 7fcd4e7..783ce8e 100644 --- a/Vali-Flow.Sql/Builder/SqlMergeBuilder.cs +++ b/Vali-Flow.Sql/Builder/SqlMergeBuilder.cs @@ -1,4 +1,6 @@ +using System.Diagnostics; using System.Linq.Expressions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Models; @@ -19,6 +21,7 @@ public sealed class SqlMergeBuilder private readonly List<(string TargetCol, string SourceExpr)> _matchedUpdateClauses = new(); private readonly List<(string TargetCol, string SourceExpr)> _notMatchedInsertClauses = new(); private bool _whenNotMatchedBySourceDelete; + private bool _allowDeleteUnmatched; private string? _tag; private readonly Dictionary _parameters = new(); private int _paramIndex; @@ -32,16 +35,16 @@ public SqlMergeBuilder(ISqlDialect dialect) /// Sets the target table for the MERGE. public SqlMergeBuilder Into(string tableName, string? schema = null) { - _targetTable = tableName ?? throw new ArgumentNullException(nameof(tableName)); - _targetSchema = schema; + _targetTable = SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName)); + _targetSchema = schema == null ? null : SqlIdentifierGuard.EnsureValidIdentifier(schema, nameof(schema)); return this; } /// Sets the source table name and alias used in the USING clause. public SqlMergeBuilder Using(string sourceTable, string alias = "src") { - _sourceTable = sourceTable ?? throw new ArgumentNullException(nameof(sourceTable)); - _sourceAlias = alias; + _sourceTable = SqlIdentifierGuard.EnsureValidIdentifier(sourceTable, nameof(sourceTable)); + _sourceAlias = SqlIdentifierGuard.EnsureValidIdentifier(alias, nameof(alias)); return this; } @@ -151,6 +154,20 @@ public SqlMergeBuilder WhenNotMatchedBySourceDelete() return this; } + // ── Safety guard ────────────────────────────────────────────────────────── + + /// + /// Explicitly allows WHEN NOT MATCHED BY SOURCE THEN DELETE to be generated. + /// Without this, Build() throws — that clause deletes every target row that has no + /// matching source row, which can wipe an entire table if the source is empty, + /// filtered, or mismatched. Call this only when deleting unmatched rows is intentional. + /// + public SqlMergeBuilder AllowDeleteUnmatched() + { + _allowDeleteUnmatched = true; + return this; + } + // ── Tag ──────────────────────────────────────────────────────────────────── /// Adds a SQL comment header and console tag for traceability. @@ -166,6 +183,23 @@ public SqlMergeBuilder Tag(string description) /// Builds and returns the parameterized MERGE statement. public SqlQueryResult Build() + { + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.Sql.SqlMergeBuilder.Build", tag: _tag, entityType: typeof(TTarget).Name); + try + { + SqlQueryResult result = BuildCore(); + activity?.SetTag("vali_flow.has_delete_unmatched", _whenNotMatchedBySourceDelete); + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private SqlQueryResult BuildCore() { if (!_dialect.SupportsMerge) throw new InvalidOperationException( @@ -185,6 +219,12 @@ public SqlQueryResult Build() throw new InvalidOperationException( "At least one of WhenMatchedUpdate(), WhenNotMatchedInsert(), or WhenNotMatchedBySourceDelete() must be called."); + if (_whenNotMatchedBySourceDelete && !_allowDeleteUnmatched) + throw new InvalidOperationException( + "WhenNotMatchedBySourceDelete() deletes every target row with no matching source row. " + + "This can wipe the entire table if the source is empty, filtered, or mismatched. " + + "Call AllowDeleteUnmatched() to explicitly confirm this is intentional."); + var parameters = new Dictionary(_parameters); var sb = new System.Text.StringBuilder(); diff --git a/Vali-Flow.Sql/Builder/SqlQueryBuilder.cs b/Vali-Flow.Sql/Builder/SqlQueryBuilder.cs index d902dd7..370541b 100644 --- a/Vali-Flow.Sql/Builder/SqlQueryBuilder.cs +++ b/Vali-Flow.Sql/Builder/SqlQueryBuilder.cs @@ -1,7 +1,9 @@ using System.Collections.Concurrent; +using System.Diagnostics; using System.Linq.Expressions; using System.Text; using System.Text.RegularExpressions; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Models; @@ -200,8 +202,7 @@ public SqlQueryBuilder SelectCast( Expression> column, string typeName, string alias) { if (column == null) throw new ArgumentNullException(nameof(column)); - if (string.IsNullOrWhiteSpace(typeName)) - throw new ArgumentException("typeName cannot be empty.", nameof(typeName)); + typeName = SqlIdentifierGuard.EnsureValidTypeName(typeName, nameof(typeName)); if (string.IsNullOrWhiteSpace(alias)) throw new ArgumentException("alias cannot be empty.", nameof(alias)); var col = _dialect.QuoteIdentifier(ExpressionHelper.GetMemberName(column)); @@ -296,10 +297,8 @@ public SqlQueryBuilder WithRecursive(string name, SqlQueryResult anchor, SqlQ /// public SqlQueryBuilder From(string tableName, string? schema = null) { - if (string.IsNullOrWhiteSpace(tableName)) - throw new ArgumentException("Table name cannot be null or empty.", nameof(tableName)); - _tableName = tableName; - _schema = schema; + _tableName = SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName)); + _schema = schema == null ? null : SqlIdentifierGuard.EnsureValidIdentifier(schema, nameof(schema)); return this; } @@ -974,7 +973,12 @@ public SqlQueryBuilder Tag(string description, Action? logger) // ── Preview ─────────────────────────────────────────────────────────────── - /// Returns a preview of the SQL mid-chain (useful in debugger watch window). + /// + /// Returns a preview of the SQL mid-chain (useful in debugger watch window). + /// Intentionally swallows any exception — the builder state may be incomplete mid-chain + /// (e.g. no table set yet), and this method must never throw since it is meant to be + /// evaluated by the debugger on every step, not called from production code paths. + /// public string ToPreviewSql() { try { return BuildInternal().Sql; } @@ -989,6 +993,23 @@ public string ToPreviewSql() // ── Internal ────────────────────────────────────────────────────────────── private SqlQueryResult BuildInternal() + { + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.Sql.SqlQueryBuilder.Build", tag: _tag, entityType: typeof(T).Name); + try + { + SqlQueryResult result = AssembleQuery(); + activity?.SetTag("vali_flow.has_where", _wherePredicate != null || _whereBuilder != null || _whereRaw.Count > 0); + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private SqlQueryResult AssembleQuery() { if (_tag != null) { diff --git a/Vali-Flow.Sql/Builder/SqlTruncateBuilder.cs b/Vali-Flow.Sql/Builder/SqlTruncateBuilder.cs index 7f0192a..d554df0 100644 --- a/Vali-Flow.Sql/Builder/SqlTruncateBuilder.cs +++ b/Vali-Flow.Sql/Builder/SqlTruncateBuilder.cs @@ -1,3 +1,5 @@ +using System.Diagnostics; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Models; @@ -26,10 +28,8 @@ public SqlTruncateBuilder(ISqlDialect dialect) /// Optional schema qualifier (e.g. "dbo"). public SqlTruncateBuilder Table(string tableName, string? schema = null) { - if (string.IsNullOrWhiteSpace(tableName)) - throw new ArgumentException("Table name cannot be null or whitespace.", nameof(tableName)); - _tableName = tableName; - _schema = schema; + _tableName = SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName)); + _schema = schema == null ? null : SqlIdentifierGuard.EnsureValidIdentifier(schema, nameof(schema)); return this; } @@ -47,18 +47,28 @@ public SqlTruncateBuilder Tag(string description) /// A with the SQL string and an empty parameters dictionary. public SqlQueryResult Build() { - if (!_dialect.SupportsTruncate) - throw new InvalidOperationException( - $"Dialect '{_dialect.DialectName}' does not support TRUNCATE TABLE. Use DELETE FROM instead."); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.Sql.SqlTruncateBuilder.Build", tag: _tag, entityType: typeof(T).Name); + try + { + if (!_dialect.SupportsTruncate) + throw new InvalidOperationException( + $"Dialect '{_dialect.DialectName}' does not support TRUNCATE TABLE. Use DELETE FROM instead."); - string quotedTable = _dialect.QuoteTable(_tableName ?? typeof(T).Name); - string tableSql = !string.IsNullOrEmpty(_schema) - ? $"{_dialect.QuoteTable(_schema)}.{quotedTable}" - : quotedTable; + string quotedTable = _dialect.QuoteTable(_tableName ?? typeof(T).Name); + string tableSql = !string.IsNullOrEmpty(_schema) + ? $"{_dialect.QuoteTable(_schema)}.{quotedTable}" + : quotedTable; - string sql = $"TRUNCATE TABLE {tableSql}"; - string finalSql = _tag != null ? $"-- {_tag}\n{sql}" : sql; + string sql = $"TRUNCATE TABLE {tableSql}"; + string finalSql = _tag != null ? $"-- {_tag}\n{sql}" : sql; - return new SqlQueryResult(finalSql, new Dictionary(), _dialect.ParameterPrefix); + return new SqlQueryResult(finalSql, new Dictionary(), _dialect.ParameterPrefix); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } } diff --git a/Vali-Flow.Sql/Builder/SqlUpdateBuilder.cs b/Vali-Flow.Sql/Builder/SqlUpdateBuilder.cs index 26871c4..19748f1 100644 --- a/Vali-Flow.Sql/Builder/SqlUpdateBuilder.cs +++ b/Vali-Flow.Sql/Builder/SqlUpdateBuilder.cs @@ -1,4 +1,7 @@ +using System.Diagnostics; using System.Linq.Expressions; +using System.Reflection; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Core.Builder; using Vali_Flow.Sql.Dialects; using Vali_Flow.Sql.Models; @@ -54,10 +57,8 @@ public SqlUpdateBuilder(ISqlDialect dialect) /// Sets the target table name and optional schema. public SqlUpdateBuilder Table(string tableName, string? schema = null) { - if (string.IsNullOrWhiteSpace(tableName)) - throw new ArgumentException("Table name cannot be null or empty.", nameof(tableName)); - _tableName = tableName; - _schema = schema; + _tableName = SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName)); + _schema = schema == null ? null : SqlIdentifierGuard.EnsureValidIdentifier(schema, nameof(schema)); return this; } @@ -74,6 +75,48 @@ public SqlUpdateBuilder Set(Expression> column, TValu return this; } + /// + /// Maps every public readable instance property of to a + /// call, reading each value from via + /// reflection. Properties listed in (typically the primary key + /// used in the WHERE clause) are skipped. + /// + /// + /// Limitations: only public instance properties are considered; indexers + /// (this[int]) and non-public properties are always skipped. Collection/complex + /// navigation properties are mapped like any other property (their raw value is passed to + /// as-is) — this method does not attempt to flatten or serialize them. + /// + public SqlUpdateBuilder SetAllFrom(T entity, params Expression>[] exclude) + { + if (entity == null) throw new ArgumentNullException(nameof(entity)); + + var excluded = exclude != null + ? new HashSet(exclude.Select(ExpressionHelper.GetMemberName)) + : new HashSet(); + + foreach (var prop in typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance)) + { + if (prop.GetIndexParameters().Length > 0) continue; + if (!prop.CanRead) continue; + if (excluded.Contains(prop.Name)) continue; + + var value = prop.GetValue(entity); + var parameter = Expression.Parameter(typeof(T), "x"); + var lambda = Expression.Lambda( + typeof(Func<,>).MakeGenericType(typeof(T), prop.PropertyType), + Expression.Property(parameter, prop), + parameter); + + var setMethod = typeof(SqlUpdateBuilder) + .GetMethod(nameof(Set))! + .MakeGenericMethod(prop.PropertyType); + setMethod.Invoke(this, new object?[] { lambda, value }); + } + + return this; + } + /// /// Adds a raw (non-parameterized) SET clause. /// .SetRaw(x => x.Counter, "Counter + 1") → [Counter] = Counter + 1 @@ -132,7 +175,11 @@ public SqlUpdateBuilder Where(Action> configure) /// both conditions are combined with AND in the final SQL. public SqlUpdateBuilder Where(Expression> predicate) { - _wherePredicate = predicate ?? throw new ArgumentNullException(nameof(predicate)); + if (predicate == null) throw new ArgumentNullException(nameof(predicate)); + if (_wherePredicate != null) + throw new InvalidOperationException( + "Where predicate already set. Combine conditions within a single expression (e.g. with &&)."); + _wherePredicate = predicate; return this; } @@ -140,8 +187,7 @@ public SqlUpdateBuilder Where(Expression> predicate) public SqlUpdateBuilder Where(ValiFlow filter) { if (filter == null) throw new ArgumentNullException(nameof(filter)); - _wherePredicate = filter.Build(); - return this; + return Where(filter.Build()); } // ── UPDATE FROM / JOIN ──────────────────────────────────────────────────── @@ -161,10 +207,8 @@ public SqlUpdateBuilder FromTable(string sourceTable, string? alias = null) if (!_dialect.SupportsUpdateFrom) throw new InvalidOperationException( $"Dialect '{_dialect.DialectName}' does not support UPDATE\u2026FROM/JOIN syntax."); - if (string.IsNullOrWhiteSpace(sourceTable)) - throw new ArgumentException("Source table name cannot be null or empty.", nameof(sourceTable)); - _fromTable = sourceTable; - _fromAlias = alias; + _fromTable = SqlIdentifierGuard.EnsureValidIdentifier(sourceTable, nameof(sourceTable)); + _fromAlias = alias == null ? null : SqlIdentifierGuard.EnsureValidIdentifier(alias, nameof(alias)); return this; } @@ -235,6 +279,24 @@ public SqlUpdateBuilder Tag(string description) /// Assembles and returns the final . public SqlQueryResult Build() + { + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.Sql.SqlUpdateBuilder.Build", tag: _tag, entityType: typeof(T).Name); + try + { + SqlQueryResult result = BuildCore(); + bool hasWhere = _wherePredicate != null || _whereBuilder != null; + activity?.SetTag("vali_flow.has_where", hasWhere); + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private SqlQueryResult BuildCore() { _paramIndex = 0; diff --git a/Vali-Flow.Sql/Extensions/ValiFlowSqlExtensions.cs b/Vali-Flow.Sql/Extensions/ValiFlowSqlExtensions.cs index ebb1a44..24eaf59 100644 --- a/Vali-Flow.Sql/Extensions/ValiFlowSqlExtensions.cs +++ b/Vali-Flow.Sql/Extensions/ValiFlowSqlExtensions.cs @@ -77,7 +77,9 @@ public static SqlQueryResult ToSqlCount( { if (dialect == null) throw new ArgumentNullException(nameof(dialect)); - string table = dialect.QuoteTable(tableName ?? typeof(T).Name); + string table = dialect.QuoteTable(tableName == null + ? typeof(T).Name + : SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName))); var parameters = new Dictionary(); string whereClause = string.Empty; @@ -138,7 +140,9 @@ public static SqlQueryResult ToSqlCount( { if (dialect == null) throw new ArgumentNullException(nameof(dialect)); - string table = dialect.QuoteTable(tableName ?? typeof(T).Name); + string table = dialect.QuoteTable(tableName == null + ? typeof(T).Name + : SqlIdentifierGuard.EnsureValidIdentifier(tableName, nameof(tableName))); var parameters = new Dictionary(); string whereClause = string.Empty; diff --git a/Vali-Flow.Sql/Vali-Flow.Sql.csproj b/Vali-Flow.Sql/Vali-Flow.Sql.csproj index 2242e96..5e7e07e 100644 --- a/Vali-Flow.Sql/Vali-Flow.Sql.csproj +++ b/Vali-Flow.Sql/Vali-Flow.Sql.csproj @@ -11,7 +11,7 @@ Vali-Flow.Sql Vali-Flow.Sql Vali-Flow.Sql - 1.1.1 + 1.2.0 Felipe Rafael Montenegro Morriberon Copyright © 2026 - FM. All rights reserved. @@ -37,7 +37,9 @@ snupkg SQL translator for Vali-Flow.Core — converts ValiFlow<T> expression trees to parameterized SQL for Dapper and ADO.NET. Supports SQL Server, PostgreSQL, MySQL, and SQLite dialects. - v1.1.1 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. + v1.2.0 — Add SqlIdentifierGuard (regex whitelist validation for table/schema/type names) to every builder, fixing a SQL injection vector. Add SetAllFrom(entity, exclude...) reflection-based bulk column mapper to Insert/Update builders. Fix OrIgnore/OrReplace dialect guard, Set()-after-SelectFrom() silent data loss, and Where()-called-twice silent overwrite bugs. Instrument all 6 builders' Build() with ValiFlowDiagnostics Activity tracing. No breaking changes. + +v1.1.1 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. v1.1.0 — Initial release. Expression-to-SQL translator with dialect support for SQL Server, PostgreSQL, MySQL, and SQLite. @@ -45,7 +47,7 @@ v1.1.0 — Initial release. Expression-to-SQL translator with dialect support fo - + diff --git a/Vali-Flow.Tests/AssemblyInfo.cs b/Vali-Flow.Tests/AssemblyInfo.cs new file mode 100644 index 0000000..db84307 --- /dev/null +++ b/Vali-Flow.Tests/AssemblyInfo.cs @@ -0,0 +1,10 @@ +using Xunit; + +// ValiFlowEfDiagnosticsTests asserts on System.Diagnostics.Activity captured via a process-wide +// ActivityListener on ValiFlowDiagnostics.Source, parenting each test's activities under a private +// root and filtering by ParentId. That reduces -- but does not fully eliminate -- cross-test +// collisions under xUnit's default test-class-level parallelism: the identical pattern was observed +// intermittently failing with "Sequence contains no matching element" in Vali-Flow.Sql.Tests (which +// has more Activity-asserting test classes competing concurrently). Disabling parallelization for +// this assembly removes that race at its source. +[assembly: CollectionBehavior(DisableTestParallelization = true)] diff --git a/Vali-Flow.Tests/BulkUpsertRetryPolicyTests.cs b/Vali-Flow.Tests/BulkUpsertRetryPolicyTests.cs new file mode 100644 index 0000000..1a09802 --- /dev/null +++ b/Vali-Flow.Tests/BulkUpsertRetryPolicyTests.cs @@ -0,0 +1,195 @@ +using FluentAssertions; +using Vali_Flow.Classes.Evaluators; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Unit tests for in isolation — no EF Core/database involved, since the +/// race it retries (concurrent bulk upsert temp-index/deadlock/busy-file failures) can't be reproduced +/// deterministically against the InMemory provider. Exercises the retry loop and transient-detection logic +/// directly via injected failing/succeeding operations and synthetic exceptions. +/// +public sealed class BulkUpsertRetryPolicyTests +{ + // ── IsTransientTempIndexFailure ────────────────────────────────────────── + + [Theory] + [InlineData("42704: index \"tempUniqueIndex_public_orders_sku\" does not exist")] + [InlineData("relation \"tempUniqueConstraint_x\" does not exist")] + [InlineData("Table 'db.tempUniqueConstraint_orders' doesn't exist")] + [InlineData("Unknown table 'tempUniqueIndex_orders' in information_schema")] + [InlineData("Transaction (Process ID 61) was deadlocked on lock resources with another process and has been chosen as the deadlock victim")] + [InlineData("database is locked")] + [InlineData("SQLite Error 5: 'database is locked'")] + public void IsTransientTempIndexFailure_KnownEngineMarkers_ReturnsTrue(string message) + { + var ex = new InvalidOperationException(message); + + BulkUpsertRetryPolicy.IsTransientTempIndexFailure(ex).Should().BeTrue(); + } + + [Fact] + public void IsTransientTempIndexFailure_MarkerInInnerException_ReturnsTrue() + { + var inner = new InvalidOperationException("42704: index \"tempUniqueIndex_x\" does not exist"); + var outer = new Exception("Bulk operation failed", inner); + + BulkUpsertRetryPolicy.IsTransientTempIndexFailure(outer).Should().BeTrue(); + } + + [Theory] + [InlineData("duplicate key value violates unique constraint \"orders_pkey\"")] + [InlineData("Column 'Name' cannot be null")] + [InlineData("Connection string is invalid")] + public void IsTransientTempIndexFailure_UnrelatedFailures_ReturnsFalse(string message) + { + var ex = new InvalidOperationException(message); + + BulkUpsertRetryPolicy.IsTransientTempIndexFailure(ex).Should().BeFalse(); + } + + [Fact] + public void IsTransientTempIndexFailure_Null_ReturnsFalse() + { + BulkUpsertRetryPolicy.IsTransientTempIndexFailure(null).Should().BeFalse(); + } + + // ── ExecuteAsync ────────────────────────────────────────────────────────── + + [Fact] + public async Task ExecuteAsync_SucceedsFirstTry_RunsOperationOnceAndDoesNotRetry() + { + var callCount = 0; + var retryCount = 0; + + await BulkUpsertRetryPolicy.ExecuteAsync( + () => { callCount++; return Task.CompletedTask; }, + CancellationToken.None, + onRetry: (_, _) => retryCount++); + + callCount.Should().Be(1); + retryCount.Should().Be(0); + } + + [Fact] + public async Task ExecuteAsync_TransientFailureThenSuccess_RetriesAndSucceeds() + { + var callCount = 0; + var retriedAttempts = new List(); + + await BulkUpsertRetryPolicy.ExecuteAsync( + () => + { + callCount++; + if (callCount < 3) throw new InvalidOperationException("database is locked"); + return Task.CompletedTask; + }, + CancellationToken.None, + onRetry: (attempt, _) => retriedAttempts.Add(attempt), + baseDelay: TimeSpan.FromMilliseconds(1), + maxDelay: TimeSpan.FromMilliseconds(5)); + + callCount.Should().Be(3); + retriedAttempts.Should().Equal(1, 2); + } + + [Fact] + public async Task ExecuteAsync_NonTransientFailure_ThrowsImmediatelyWithoutRetrying() + { + var callCount = 0; + + Func act = () => BulkUpsertRetryPolicy.ExecuteAsync( + () => { callCount++; throw new InvalidOperationException("Column 'Name' cannot be null"); }, + CancellationToken.None, + baseDelay: TimeSpan.FromMilliseconds(1)); + + await act.Should().ThrowAsync().WithMessage("Column 'Name' cannot be null"); + callCount.Should().Be(1); + } + + [Fact] + public async Task ExecuteAsync_TransientFailureExhaustsMaxAttempts_ThrowsLastException() + { + var callCount = 0; + + Func act = () => BulkUpsertRetryPolicy.ExecuteAsync( + () => { callCount++; throw new InvalidOperationException("database is locked"); }, + CancellationToken.None, + maxAttempts: 3, + baseDelay: TimeSpan.FromMilliseconds(1), + maxDelay: TimeSpan.FromMilliseconds(5)); + + await act.Should().ThrowAsync().WithMessage("database is locked"); + callCount.Should().Be(3); + } + + [Fact] + public async Task ExecuteAsync_CustomIsTransientPredicate_OverridesDefaultDetection() + { + var callCount = 0; + + await BulkUpsertRetryPolicy.ExecuteAsync( + () => + { + callCount++; + if (callCount < 2) throw new ArgumentException("custom-marker"); + return Task.CompletedTask; + }, + CancellationToken.None, + isTransient: ex => ex is ArgumentException, + baseDelay: TimeSpan.FromMilliseconds(1)); + + callCount.Should().Be(2); + } + + [Fact] + public async Task ExecuteAsync_CancellationRequestedBeforeAttempt_ThrowsOperationCanceled() + { + using var cts = new CancellationTokenSource(); + cts.Cancel(); + + Func act = () => BulkUpsertRetryPolicy.ExecuteAsync( + () => Task.CompletedTask, + cts.Token); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task ExecuteAsync_CancellationDuringBackoffDelay_PropagatesWithoutFurtherRetries() + { + using var cts = new CancellationTokenSource(); + var callCount = 0; + + Func act = () => BulkUpsertRetryPolicy.ExecuteAsync( + () => + { + callCount++; + cts.Cancel(); + throw new InvalidOperationException("database is locked"); + }, + cts.Token, + baseDelay: TimeSpan.FromMilliseconds(50)); + + await act.Should().ThrowAsync(); + callCount.Should().Be(1); + } + + [Fact] + public void ExecuteAsync_NullOperation_ThrowsArgumentNullException() + { + Func act = () => BulkUpsertRetryPolicy.ExecuteAsync(null!, CancellationToken.None); + + act.Should().ThrowAsync(); + } + + [Fact] + public void ExecuteAsync_MaxAttemptsLessThanOne_ThrowsArgumentOutOfRangeException() + { + Func act = () => BulkUpsertRetryPolicy.ExecuteAsync( + () => Task.CompletedTask, CancellationToken.None, maxAttempts: 0); + + act.Should().ThrowAsync(); + } +} diff --git a/Vali-Flow.Tests/GenericRepositoryTests.cs b/Vali-Flow.Tests/GenericRepositoryTests.cs new file mode 100644 index 0000000..f4e39c6 --- /dev/null +++ b/Vali-Flow.Tests/GenericRepositoryTests.cs @@ -0,0 +1,155 @@ +using FluentAssertions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Repository; +using Vali_Flow.Core.Builder; +using Vali_Flow.Interfaces.Repository; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +public sealed class GenericRepositoryTests +{ + // ── Helpers ─────────────────────────────────────────────────────────────── + + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + private static async Task CreateSeededContextAsync() + { + var ctx = CreateContext(); + ctx.Orders.AddRange( + new TestOrder { Id = 1, CustomerName = "Alice", Total = 150m, IsShipped = true, CreatedAt = new DateTime(2024, 1, 1) }, + new TestOrder { Id = 2, CustomerName = "Bob", Total = 320m, IsShipped = false, CreatedAt = new DateTime(2024, 2, 1) }, + new TestOrder { Id = 3, CustomerName = "Carol", Total = 80m, IsShipped = true, CreatedAt = new DateTime(2024, 3, 1) } + ); + await ctx.SaveChangesAsync(); + ctx.ChangeTracker.Clear(); + return ctx; + } + + private static IGenericRepository CreateRepository(TestDbContext ctx) => + new GenericRepository(new ValiFlowEvaluator(ctx), o => o.Id); + + // ── GetByIdAsync ────────────────────────────────────────────────────────── + + [Fact] + public async Task GetByIdAsync_ExistingId_ReturnsEntity() + { + await using var ctx = await CreateSeededContextAsync(); + var repository = CreateRepository(ctx); + + var order = await repository.GetByIdAsync(2); + + order.Should().NotBeNull(); + order!.CustomerName.Should().Be("Bob"); + } + + [Fact] + public async Task GetByIdAsync_MissingId_ReturnsNull() + { + await using var ctx = await CreateSeededContextAsync(); + var repository = CreateRepository(ctx); + + var order = await repository.GetByIdAsync(999); + + order.Should().BeNull(); + } + + // ── GetAllAsync ─────────────────────────────────────────────────────────── + + [Fact] + public async Task GetAllAsync_NoFilter_ReturnsAllEntities() + { + await using var ctx = await CreateSeededContextAsync(); + var repository = CreateRepository(ctx); + + var orders = await repository.GetAllAsync(); + + orders.Should().HaveCount(3); + } + + [Fact] + public async Task GetAllAsync_WithFilter_ReturnsOnlyMatchingEntities() + { + await using var ctx = await CreateSeededContextAsync(); + var repository = CreateRepository(ctx); + var filter = new ValiFlowQuery().IsTrue(o => o.IsShipped); + + var orders = await repository.GetAllAsync(filter); + + orders.Should().HaveCount(2).And.OnlyContain(o => o.IsShipped); + } + + // ── GetPagedAsync ───────────────────────────────────────────────────────── + + [Fact] + public async Task GetPagedAsync_ReturnsCorrectPageAndMetadata() + { + await using var ctx = await CreateSeededContextAsync(); + var repository = CreateRepository(ctx); + + var paged = await repository.GetPagedAsync(null, o => o.Id, page: 1, pageSize: 2); + + paged.Items.Should().HaveCount(2); + paged.TotalCount.Should().Be(3); + paged.Page.Should().Be(1); + paged.PageSize.Should().Be(2); + paged.Items.Select(o => o.Id).Should().BeInAscendingOrder(); + } + + // ── AddAsync / UpdateAsync / DeleteAsync / SaveChangesAsync ────────────── + + [Fact] + public async Task AddAsync_PersistsEntity() + { + await using var ctx = CreateContext(); + var repository = CreateRepository(ctx); + var newOrder = new TestOrder { Id = 10, CustomerName = "Frank", Total = 99m, CreatedAt = DateTime.UtcNow }; + + await repository.AddAsync(newOrder); + + (await repository.GetByIdAsync(10)).Should().NotBeNull(); + } + + [Fact] + public async Task UpdateAsync_PersistsChanges() + { + await using var ctx = await CreateSeededContextAsync(); + var repository = CreateRepository(ctx); + var order = await repository.GetByIdAsync(1); + order!.CustomerName = "Alice Updated"; + + await repository.UpdateAsync(order); + + (await repository.GetByIdAsync(1))!.CustomerName.Should().Be("Alice Updated"); + } + + [Fact] + public async Task DeleteAsync_RemovesEntity() + { + await using var ctx = await CreateSeededContextAsync(); + var repository = CreateRepository(ctx); + var order = await repository.GetByIdAsync(3); + + await repository.DeleteAsync(order!); + + (await repository.GetByIdAsync(3)).Should().BeNull(); + } + + [Fact] + public async Task AddAsync_WithSaveChangesFalse_DoesNotPersistUntilSaveChangesAsyncCalled() + { + await using var ctx = CreateContext(); + var repository = CreateRepository(ctx); + var newOrder = new TestOrder { Id = 20, CustomerName = "Grace", Total = 10m, CreatedAt = DateTime.UtcNow }; + + await repository.AddAsync(newOrder, saveChanges: false); + ctx.ChangeTracker.Clear(); + (await repository.GetByIdAsync(20)).Should().BeNull(); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfBridgeTests.cs b/Vali-Flow.Tests/ValiFlowEfBridgeTests.cs new file mode 100644 index 0000000..372cca5 --- /dev/null +++ b/Vali-Flow.Tests/ValiFlowEfBridgeTests.cs @@ -0,0 +1,323 @@ +using System.Numerics; +using FluentAssertions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Abstractions.Interfaces; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Core.Builder; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Covers ValiFlowEvaluator.Bridge.cs — the explicit IQueryReader<T>/IQueryAggregator<T> +/// implementations reachable only by casting the evaluator to those provider-agnostic interfaces +/// (the public spec-based overloads with the same names are separate members, covered elsewhere). +/// +public sealed class ValiFlowEfBridgeTests +{ + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + private static async Task CreateSeededContextAsync() + { + var ctx = CreateContext(); + ctx.Orders.AddRange( + new TestOrder { Id = 1, CustomerName = "Alice", Total = 150m, IsShipped = true, CreatedAt = new DateTime(2024, 1, 1) }, + new TestOrder { Id = 2, CustomerName = "Bob", Total = 320m, IsShipped = false, CreatedAt = new DateTime(2024, 2, 1) }, + new TestOrder { Id = 3, CustomerName = "Carol", Total = 80m, IsShipped = true, CreatedAt = new DateTime(2024, 3, 1) } + ); + await ctx.SaveChangesAsync(); + return ctx; + } + + // ── IQueryReader.EvaluateAnyAsync / EvaluateCountAsync / EvaluateGetFirstAsync ── + + [Fact] + public async Task IQueryReader_EvaluateAnyAsync_WithFilter_ReturnsTrue() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryReader reader = new ValiFlowEvaluator(ctx); + + var result = await reader.EvaluateAnyAsync(new ValiFlow().IsTrue(o => o.IsShipped)); + + result.Should().BeTrue(); + } + + [Fact] + public async Task IQueryReader_EvaluateAnyAsync_NoFilter_ReturnsTrue() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryReader reader = new ValiFlowEvaluator(ctx); + + var result = await reader.EvaluateAnyAsync(); + + result.Should().BeTrue(); + } + + [Fact] + public async Task IQueryReader_EvaluateCountAsync_WithFilter_ReturnsMatchingCount() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryReader reader = new ValiFlowEvaluator(ctx); + + var count = await reader.EvaluateCountAsync(new ValiFlow().IsTrue(o => o.IsShipped)); + + count.Should().Be(2); + } + + [Fact] + public async Task IQueryReader_EvaluateGetFirstAsync_NoFilter_ReturnsAnEntity() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryReader reader = new ValiFlowEvaluator(ctx); + + var result = await reader.EvaluateGetFirstAsync(); + + result.Should().NotBeNull(); + } + + [Fact] + public async Task IQueryReader_EvaluateGetLastAsync_NoFilter_ReturnsLastByPrimaryKey() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryReader reader = new ValiFlowEvaluator(ctx); + + var result = await reader.EvaluateGetLastAsync(); + + result.Should().NotBeNull(); + result!.Id.Should().Be(3); + } + + [Fact] + public async Task IQueryReader_EvaluateGetLastAsync_WithFilter_ReturnsLastMatching() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryReader reader = new ValiFlowEvaluator(ctx); + + var result = await reader.EvaluateGetLastAsync(new ValiFlow().IsTrue(o => o.IsShipped)); + + result.Should().NotBeNull(); + result!.Id.Should().Be(3); + } + + // ── IQueryAggregator.EvaluateMinAsync / EvaluateMaxAsync ─────────────────── + + [Fact] + public async Task IQueryAggregator_EvaluateMinAsync_EmptyResult_ReturnsDefault() + { + await using var ctx = CreateContext(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateMinAsync(o => o.Total); + + result.Should().Be(0m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateMinAsync_WithData_ReturnsMin() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateMinAsync(o => o.Total); + + result.Should().Be(80m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateMaxAsync_EmptyResult_ReturnsDefault() + { + await using var ctx = CreateContext(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateMaxAsync(o => o.Total); + + result.Should().Be(0m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateMaxAsync_WithFilter_ReturnsMax() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateMaxAsync(o => o.Total, new ValiFlow().IsTrue(o => o.IsShipped)); + + result.Should().Be(150m); + } + + // ── IQueryAggregator.EvaluateAverageAsync — one branch per supported numeric type ── + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_EmptyResult_ReturnsZero() + { + await using var ctx = CreateContext(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => o.Total); + + result.Should().Be(0m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_DecimalSelector_ReturnsAverage() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => o.Total); + + result.Should().BeApproximately(183.33m, 0.01m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_DoubleSelector_ReturnsAverage() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => (double)o.Total); + + result.Should().BeApproximately(183.33m, 0.01m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_FloatSelector_ReturnsAverage() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => (float)o.Total); + + result.Should().BeApproximately(183.33m, 0.1m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_LongSelector_ReturnsAverage() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => (long)o.Total); + + result.Should().BeApproximately(183.33m, 0.01m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_IntSelector_ReturnsAverage() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => (int)o.Total); + + result.Should().BeApproximately(183.33m, 0.01m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_ExoticNumericSelector_FallsBackToInMemory() + { + // BigInteger implements INumber but matches none of the Average fast-path overloads, + // exercising the materialize-and-average fallback branch. + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => (BigInteger)o.Total); + + result.Should().BeApproximately(183.33m, 0.01m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateAverageAsync_ExoticNumericSelector_EmptyResult_ReturnsZero() + { + await using var ctx = CreateContext(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateAverageAsync(o => (BigInteger)o.Total); + + result.Should().Be(0m); + } + + // ── IQueryAggregator.EvaluateSumAsync — one branch per supported numeric type + fallback ── + + [Fact] + public async Task IQueryAggregator_EvaluateSumAsync_DecimalSelector_ReturnsSum() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateSumAsync(o => o.Total); + + result.Should().Be(550m); + } + + [Fact] + public async Task IQueryAggregator_EvaluateSumAsync_DoubleSelector_ReturnsSum() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateSumAsync(o => (double)o.Total); + + result.Should().Be(550d); + } + + [Fact] + public async Task IQueryAggregator_EvaluateSumAsync_FloatSelector_ReturnsSum() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateSumAsync(o => (float)o.Total); + + result.Should().Be(550f); + } + + [Fact] + public async Task IQueryAggregator_EvaluateSumAsync_LongSelector_ReturnsSum() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateSumAsync(o => (long)o.Total); + + result.Should().Be(550L); + } + + [Fact] + public async Task IQueryAggregator_EvaluateSumAsync_IntSelector_ReturnsSum() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateSumAsync(o => (int)o.Total); + + result.Should().Be(550); + } + + [Fact] + public async Task IQueryAggregator_EvaluateSumAsync_ExoticNumericSelector_EmptyResult_ReturnsZero() + { + await using var ctx = CreateContext(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateSumAsync(o => (BigInteger)o.Total); + + result.Should().Be(BigInteger.Zero); + } + + [Fact] + public async Task IQueryAggregator_EvaluateSumAsync_ExoticNumericSelector_FallsBackToInMemory() + { + await using var ctx = await CreateSeededContextAsync(); + IQueryAggregator aggregator = new ValiFlowEvaluator(ctx); + + var result = await aggregator.EvaluateSumAsync(o => (BigInteger)o.Total); + + result.Should().Be(new BigInteger(550)); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfBulkTests.cs b/Vali-Flow.Tests/ValiFlowEfBulkTests.cs index 889edf3..6adbd2b 100644 --- a/Vali-Flow.Tests/ValiFlowEfBulkTests.cs +++ b/Vali-Flow.Tests/ValiFlowEfBulkTests.cs @@ -483,5 +483,58 @@ public async Task BulkInsertOrUpdateAsync_WithBulkConfig_RespectsConfig() (await ctx.Orders.CountAsync()).Should().Be(10); } + [Fact] + public async Task BulkInsertOrUpdateAsync_ConcurrentCallsSameEntityType_SerializedWithoutExceptions() + { + // Regression test for the in-process gate added around BulkInsertOrUpdateAsync (see + // ValiFlowEvaluator.Write.cs, GetBulkUpsertGate/RunGatedBulkInsertOrUpdateAsync). Found against + // a real Postgres instance via the Vali-Flow stress-test harness: EFCore.BulkExtensions' + // PostgreSQL adapter upserts through a deterministic temp unique index name + // (tempUniqueIndex_{schema}_{table}_{column}); concurrent calls targeting the same table/key + // race on create/drop of that shared index and fail with + // "42704: index tempUniqueIndex_... does not exist". SQLite doesn't share that adapter + // internals, so this test can't reproduce the exact exception, but it does verify the new + // gate doesn't corrupt results or deadlock under real concurrent callers. + await using var sqlCtx = SqliteTestContext.Create(); + var ctx = sqlCtx.Context; + var evaluator = new ValiFlowEvaluator(ctx); + + // The gate is keyed per entity type (table), not per UpdateByProperties -- every call below + // shares the same gate regardless of which key columns it matches on. + const int concurrentCallers = 8; + var tasks = Enumerable.Range(0, concurrentCallers).Select(i => evaluator.BulkInsertOrUpdateAsync( + new List + { + new() { Id = 1000 + i, CustomerName = $"Concurrent{i}", Total = i, IsShipped = false, CreatedAt = DateTime.UtcNow } + })); + + Func act = async () => await Task.WhenAll(tasks); + await act.Should().NotThrowAsync(); + + (await ctx.Orders.CountAsync(o => o.CustomerName!.StartsWith("Concurrent"))).Should().Be(concurrentCallers); + } + + [Fact] + public async Task BulkUpdateAsync_ConcurrentCallsSameEntityType_SharesGateWithInsertOrUpdateAndDoesNotThrow() + { + // BulkUpdateAsync shares the exact same temp-index/deadlock exposure as BulkInsertOrUpdateAsync + // when matching by BulkConfig.UpdateByProperties (see BulkUpsertRetryPolicy) -- it now goes + // through the same gate+retry path (RunGatedBulkUpsertAsync). Verifies concurrent calls against + // the same entity type don't corrupt results or deadlock. + await using var sqlCtx = SqliteTestContext.Create(); + var ctx = sqlCtx.Context; + ctx_seed(ctx); + await ctx.SaveChangesAsync(); + var evaluator = new ValiFlowEvaluator(ctx); + + var seeded = await ctx.Orders.AsNoTracking().ToListAsync(); + const int concurrentCallers = 8; + var tasks = seeded.Take(concurrentCallers).Select((o, i) => evaluator.BulkUpdateAsync( + new List { new() { Id = o.Id, CustomerName = o.CustomerName, Total = 100 + i, IsShipped = true, CreatedAt = o.CreatedAt } })); + + Func act = async () => await Task.WhenAll(tasks); + await act.Should().NotThrowAsync(); + } + private static void ctx_seed(TestDbContext ctx) => ctx.Orders.AddRange(SeedOrders()); } diff --git a/Vali-Flow.Tests/ValiFlowEfDiagnosticsTests.cs b/Vali-Flow.Tests/ValiFlowEfDiagnosticsTests.cs new file mode 100644 index 0000000..c966cc2 --- /dev/null +++ b/Vali-Flow.Tests/ValiFlowEfDiagnosticsTests.cs @@ -0,0 +1,152 @@ +using System.Diagnostics; +using FluentAssertions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Abstractions.Diagnostics; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Verifies that read/write operations open a +/// with the expected name/tags, +/// and mark it as failed when the underlying operation throws. +/// +public sealed class ValiFlowEfDiagnosticsTests +{ + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + /// + /// Attaches a listener and parents every captured activity under a private root, so concurrently + /// running tests (xunit parallelizes test classes by default) can never pollute this test's capture + /// list even though they share the same process-wide . + /// + private static (ActivityListener Listener, Activity Root, List Captured) AttachScopedListener() + { + var captured = new List(); + var listener = new ActivityListener + { + ShouldListenTo = source => source.Name == ValiFlowDiagnostics.SourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllData, + ActivityStopped = captured.Add + }; + ActivitySource.AddActivityListener(listener); + + var root = new Activity("TestRoot").Start(); // becomes Activity.Current -> parents child activities + return (listener, root, captured); + } + + private static Activity GetOwn(List captured, Activity root, string operationName) + => captured.Single(a => a.OperationName == operationName && a.ParentId == root.Id); + + [Fact] + public async Task EvaluateCountAsync_WithTagWith_StartsActivityWithExpectedNameAndTag() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + await using var ctx = CreateContext(); + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new BasicSpecification(new ValiFlowQuery()) + .WithTagWith("MyReport"); + + await evaluator.EvaluateCountAsync(spec); + + Activity activity = GetOwn(captured, root, "Vali-Flow.EvaluateCountAsync"); + activity.GetTagItem("vali_flow.tag").Should().Be("MyReport"); + activity.GetTagItem("vali_flow.entity_type").Should().Be(nameof(TestOrder)); + activity.Status.Should().Be(ActivityStatusCode.Unset); + } + + [Fact] + public async Task EvaluateAnyAsync_SetsHasFilterAndIncludeCountTags() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + await using var ctx = CreateContext(); + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new BasicSpecification(new ValiFlowQuery().IsTrue(o => o.IsShipped)); + + await evaluator.EvaluateAnyAsync(spec); + + Activity activity = GetOwn(captured, root, "Vali-Flow.EvaluateAnyAsync"); + activity.GetTagItem("vali_flow.has_filter").Should().Be(true); + activity.GetTagItem("vali_flow.include_count").Should().Be(0); + } + + [Fact] + public async Task AddAsync_NullEntity_RecordsActivityAsError() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + await using var ctx = CreateContext(); + var evaluator = new ValiFlowEvaluator(ctx); + + Func act = () => evaluator.AddAsync(null!); + + await act.Should().ThrowAsync(); + + Activity activity = GetOwn(captured, root, "Vali-Flow.AddAsync"); + activity.Status.Should().Be(ActivityStatusCode.Error); + activity.Events.Should().ContainSingle(e => e.Name == "exception"); + } + + [Fact] + public async Task ExecuteTransactionAsync_OperationThrows_RecordsActivityAsError() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + await using var ctx = CreateContext(); + var evaluator = new ValiFlowEvaluator(ctx); + + Func act = () => evaluator.ExecuteTransactionAsync( + () => throw new InvalidOperationException("boom")); + + // The InMemory provider does not support transactions, so BeginTransactionAsync itself + // throws — either way the operation fails and the activity must be recorded as errored. + await act.Should().ThrowAsync(); + + Activity activity = GetOwn(captured, root, "Vali-Flow.ExecuteTransactionAsync"); + activity.Status.Should().Be(ActivityStatusCode.Error); + activity.Events.Should().ContainSingle(e => e.Name == "exception"); + } + + [Fact] + public async Task EvaluatePagedAsync_SetsPageAndPageSizeTags() + { + var (listener, root, captured) = AttachScopedListener(); + using var l = listener; + using var r = root; + + await using var ctx = CreateContext(); + ctx.Orders.Add(new TestOrder { Id = 1, CustomerName = "Alice", Total = 10m, CreatedAt = DateTime.UtcNow }); + await ctx.SaveChangesAsync(); + + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification(new ValiFlowQuery()) + .WithPage(1) + .WithPageSize(10) + .WithOrderBy(o => o.Id); + + await evaluator.EvaluatePagedAsync(spec); + + Activity activity = GetOwn(captured, root, "Vali-Flow.EvaluatePagedAsync"); + activity.GetTagItem("vali_flow.page").Should().Be(1); + activity.GetTagItem("vali_flow.page_size").Should().Be(10); + activity.GetTagItem("vali_flow.has_pagination").Should().Be(true); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfFinalGapsTests.cs b/Vali-Flow.Tests/ValiFlowEfFinalGapsTests.cs new file mode 100644 index 0000000..6636824 --- /dev/null +++ b/Vali-Flow.Tests/ValiFlowEfFinalGapsTests.cs @@ -0,0 +1,274 @@ +using FluentAssertions; +using Microsoft.Data.Sqlite; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Targets the remaining catch(Exception)/RecordException branches and a handful of guard clauses that +/// were still at 0% after the broader coverage pass: write-method catch blocks (null entity/entities +/// propagating through the try), pre-canceled-token catch paths on read methods whose null guard sits +/// outside the try, EvaluatePagedAsync's Page/PageSize-individually-missing guards, EvaluateDistinctAsync/ +/// EvaluateDuplicatesAsync's null-selector and pagination-without-ordering guards, the relational +/// (non-InMemory) branch of DeleteByConditionCoreAsync, and the "rollback itself fails" branch of +/// RollbackTransactionAsync. +/// +public sealed class ValiFlowEfFinalGapsTests +{ + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + private static async Task CreateSeededContextAsync() + { + var ctx = CreateContext(); + ctx.Orders.AddRange( + new TestOrder { Id = 1, CustomerName = "Alice", Total = 150m, IsShipped = true, CreatedAt = new DateTime(2024, 1, 1) }, + new TestOrder { Id = 2, CustomerName = "Bob", Total = 320m, IsShipped = false, CreatedAt = new DateTime(2024, 2, 1) } + ); + await ctx.SaveChangesAsync(); + return ctx; + } + + // ── Write-method catch blocks: null entity/entities propagates through try ── + + [Fact] + public async Task DeleteAsync_NullEntity_RecordsAndRethrows() + { + await using var ctx = CreateContext(); + var ev = new ValiFlowEvaluator(ctx); + + Func act = () => ev.DeleteAsync(null!); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task UpdateAsync_NullEntity_RecordsAndRethrows() + { + await using var ctx = CreateContext(); + var ev = new ValiFlowEvaluator(ctx); + + Func act = () => ev.UpdateAsync(null!); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task UpsertAsync_NullEntity_RecordsAndRethrows() + { + await using var ctx = CreateContext(); + var ev = new ValiFlowEvaluator(ctx); + + Func act = () => ev.UpsertAsync(null!, o => o.Id == 1); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task BulkInsertOrUpdateAsync_NullEntities_RecordsAndRethrows() + { + await using var ctx = CreateContext(); + var ev = new ValiFlowEvaluator(ctx); + + Func act = () => ev.BulkInsertOrUpdateAsync(null!); + + await act.Should().ThrowAsync(); + } + + // ── Pre-canceled-token catch paths (null guard sits outside the try) ───── + + [Fact] + public async Task EvaluateGetFirstAsync_PreCanceledToken_ThrowsWithCanceledInner() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new BasicSpecification(); + var ct = new CancellationToken(canceled: true); + + Func act = () => ev.EvaluateGetFirstAsync(spec, ct); + + var ex = await act.Should().ThrowAsync(); + ex.Which.InnerException.Should().BeAssignableTo(); + } + + [Fact] + public async Task EvaluateGetFirstFailedAsync_PreCanceledToken_ThrowsWithCanceledInner() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new BasicSpecification(); + var ct = new CancellationToken(canceled: true); + + Func act = () => ev.EvaluateGetFirstFailedAsync(spec, ct); + + var ex = await act.Should().ThrowAsync(); + ex.Which.InnerException.Should().BeAssignableTo(); + } + + [Fact] + public async Task DeleteByConditionAsync_PreCanceledToken_ThrowsWithCanceledInner() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var ct = new CancellationToken(canceled: true); + + Func act = () => ev.DeleteByConditionAsync(o => o.Id == 1, ct); + + var ex = await act.Should().ThrowAsync(); + ex.Which.InnerException.Should().BeAssignableTo(); + } + + // ── EvaluateGetLastAsync / EvaluateGetLastFailedAsync — pagination guard ── + + [Fact] + public async Task EvaluateGetLastAsync_PageSet_ThrowsInvalidOperationException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithPage(1); + + Func act = () => ev.EvaluateGetLastAsync(spec); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateGetLastFailedAsync_PageSet_ThrowsInvalidOperationException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithPage(1); + + Func act = () => ev.EvaluateGetLastFailedAsync(spec); + + await act.Should().ThrowAsync(); + } + + // ── EvaluatePagedAsync — Page/PageSize missing individually ─────────────── + + [Fact] + public async Task EvaluatePagedAsync_PageSizeSetWithoutPage_ThrowsArgumentException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithOrderBy(o => o.Id).WithPageSize(10); + + Func act = () => ev.EvaluatePagedAsync(spec); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluatePagedAsync_PageSetWithoutPageSize_ThrowsArgumentException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithOrderBy(o => o.Id).WithPage(1); + + Func act = () => ev.EvaluatePagedAsync(spec); + + await act.Should().ThrowAsync(); + } + + // ── EvaluateDistinctAsync / EvaluateDuplicatesAsync guards ──────────────── + + [Fact] + public async Task EvaluateDistinctAsync_NullSelector_ThrowsArgumentNullException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification(); + + Func act = () => ev.EvaluateDistinctAsync(spec, null!); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateDistinctAsync_PaginationWithoutOrdering_ThrowsInvalidOperationException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithTop(5); + + Func act = () => ev.EvaluateDistinctAsync(spec, o => o.CustomerName); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateDuplicatesAsync_NullSelector_ThrowsArgumentNullException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification(); + + Func act = () => ev.EvaluateDuplicatesAsync(spec, null!); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateDuplicatesAsync_PaginationWithoutOrdering_ThrowsInvalidOperationException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithTop(5); + + Func act = () => ev.EvaluateDuplicatesAsync(spec, o => o.CustomerName); + + await act.Should().ThrowAsync(); + } + + // ── DeleteByConditionCoreAsync — relational (non-InMemory) branch ───────── + + [Fact] + public async Task DeleteByConditionAsync_RelationalProvider_UsesExecuteDeleteAsync() + { + using var connection = new SqliteConnection("DataSource=:memory:"); + connection.Open(); + var options = new DbContextOptionsBuilder().UseSqlite(connection).Options; + await using var ctx = new TestDbContext(options); + await ctx.Database.EnsureCreatedAsync(); + ctx.Orders.Add(new TestOrder { Id = 1, CustomerName = "Alice", Total = 10m, IsShipped = false, CreatedAt = DateTime.UtcNow }); + await ctx.SaveChangesAsync(); + + var ev = new ValiFlowEvaluator(ctx); + + await ev.DeleteByConditionAsync(o => o.Id == 1); + + (await ctx.Orders.CountAsync()).Should().Be(0); + } + + // ── RollbackTransactionAsync — rollback itself fails ────────────────────── + + [Fact] + public async Task ExecuteTransactionAsync_RollbackAlsoFails_ThrowsAggregateException() + { + using var connection = new SqliteConnection("DataSource=:memory:"); + connection.Open(); + var options = new DbContextOptionsBuilder().UseSqlite(connection).Options; + await using var ctx = new TestDbContext(options); + await ctx.Database.EnsureCreatedAsync(); + + var ev = new ValiFlowEvaluator(ctx); + + Func act = () => ev.ExecuteTransactionAsync(async () => + { + // Sabotage the connection so the subsequent RollbackAsync call inside the evaluator's own + // failure-handling path throws too, exercising the "rollback also failed" branch. + await connection.CloseAsync(); + throw new InvalidOperationException("boom"); + }); + + await act.Should().ThrowAsync(); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfGroupedNumericOverloadsTests.cs b/Vali-Flow.Tests/ValiFlowEfGroupedNumericOverloadsTests.cs new file mode 100644 index 0000000..2c5ba01 --- /dev/null +++ b/Vali-Flow.Tests/ValiFlowEfGroupedNumericOverloadsTests.cs @@ -0,0 +1,152 @@ +using FluentAssertions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Covers the long/float/double overloads of EvaluateSumByGroupAsync/EvaluateMinByGroupAsync/ +/// EvaluateMaxByGroupAsync. The int and decimal overloads are already covered by +/// ValiFlowEfGroupedAsyncTests/ValiFlowEfGroupedTests — every overload shares the same body shape +/// (just a different selector type), so one happy-path test per overload is enough to hit its branch. +/// +public sealed class ValiFlowEfGroupedNumericOverloadsTests +{ + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + private static async Task CreateSeededContextAsync() + { + var ctx = CreateContext(); + ctx.Orders.AddRange( + new TestOrder { Id = 1, CustomerName = "Alice", Total = 150m, IsShipped = true, CreatedAt = new DateTime(2024, 1, 1) }, + new TestOrder { Id = 2, CustomerName = "Bob", Total = 320m, IsShipped = false, CreatedAt = new DateTime(2024, 2, 1) }, + new TestOrder { Id = 3, CustomerName = "Carol", Total = 80m, IsShipped = true, CreatedAt = new DateTime(2024, 3, 1) } + ); + await ctx.SaveChangesAsync(); + return ctx; + } + + private static BasicSpecification AllOrders() => new(new ValiFlowQuery()); + + // ── EvaluateSumByGroupAsync ──────────────────────────────────────────────── + + [Fact] + public async Task EvaluateSumByGroupAsync_LongSelector_ByIsShipped_CorrectSums() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var sums = await ev.EvaluateSumByGroupAsync(AllOrders(), o => o.IsShipped, o => (long)o.Total); + + sums[true].Should().Be(230L); + sums[false].Should().Be(320L); + } + + [Fact] + public async Task EvaluateSumByGroupAsync_FloatSelector_ByIsShipped_CorrectSums() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var sums = await ev.EvaluateSumByGroupAsync(AllOrders(), o => o.IsShipped, o => (float)o.Total); + + sums[true].Should().Be(230f); + sums[false].Should().Be(320f); + } + + [Fact] + public async Task EvaluateSumByGroupAsync_DoubleSelector_ByIsShipped_CorrectSums() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var sums = await ev.EvaluateSumByGroupAsync(AllOrders(), o => o.IsShipped, o => (double)o.Total); + + sums[true].Should().Be(230d); + sums[false].Should().Be(320d); + } + + // ── EvaluateMinByGroupAsync ──────────────────────────────────────────────── + + [Fact] + public async Task EvaluateMinByGroupAsync_LongSelector_ByIsShipped_CorrectMins() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var mins = await ev.EvaluateMinByGroupAsync(AllOrders(), o => o.IsShipped, o => (long)o.Total); + + mins[true].Should().Be(80L); + mins[false].Should().Be(320L); + } + + [Fact] + public async Task EvaluateMinByGroupAsync_FloatSelector_ByIsShipped_CorrectMins() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var mins = await ev.EvaluateMinByGroupAsync(AllOrders(), o => o.IsShipped, o => (float)o.Total); + + mins[true].Should().Be(80f); + mins[false].Should().Be(320f); + } + + [Fact] + public async Task EvaluateMinByGroupAsync_DoubleSelector_ByIsShipped_CorrectMins() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var mins = await ev.EvaluateMinByGroupAsync(AllOrders(), o => o.IsShipped, o => (double)o.Total); + + mins[true].Should().Be(80d); + mins[false].Should().Be(320d); + } + + // ── EvaluateMaxByGroupAsync ──────────────────────────────────────────────── + + [Fact] + public async Task EvaluateMaxByGroupAsync_LongSelector_ByIsShipped_CorrectMaxes() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var maxes = await ev.EvaluateMaxByGroupAsync(AllOrders(), o => o.IsShipped, o => (long)o.Total); + + maxes[true].Should().Be(150L); + maxes[false].Should().Be(320L); + } + + [Fact] + public async Task EvaluateMaxByGroupAsync_FloatSelector_ByIsShipped_CorrectMaxes() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var maxes = await ev.EvaluateMaxByGroupAsync(AllOrders(), o => o.IsShipped, o => (float)o.Total); + + maxes[true].Should().Be(150f); + maxes[false].Should().Be(320f); + } + + [Fact] + public async Task EvaluateMaxByGroupAsync_DoubleSelector_ByIsShipped_CorrectMaxes() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var maxes = await ev.EvaluateMaxByGroupAsync(AllOrders(), o => o.IsShipped, o => (double)o.Total); + + maxes[true].Should().Be(150d); + maxes[false].Should().Be(320d); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfLastGapsTests.cs b/Vali-Flow.Tests/ValiFlowEfLastGapsTests.cs new file mode 100644 index 0000000..301ce1a --- /dev/null +++ b/Vali-Flow.Tests/ValiFlowEfLastGapsTests.cs @@ -0,0 +1,91 @@ +using FluentAssertions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Last few stragglers: EvaluateQueryFailedAsync's catch block, EvaluateTopAsync combined with +/// pagination, QuerySpecification's 4-arg constructor overload, QuerySpecification.WithTop after +/// Page/PageSize already set, and Validation.ValidateFilterNotNull via a specification with a null Filter +/// (unreachable through BasicSpecification's own constructors, which never allow a null Filter — only a +/// custom ISpecification{T} can produce one). +/// +public sealed class ValiFlowEfLastGapsTests +{ + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + private static async Task CreateSeededContextAsync() + { + var ctx = CreateContext(); + ctx.Orders.Add(new TestOrder { Id = 1, CustomerName = "Alice", Total = 10m, IsShipped = false, CreatedAt = DateTime.UtcNow }); + await ctx.SaveChangesAsync(); + return ctx; + } + + [Fact] + public async Task EvaluateQueryFailedAsync_PageWithoutPageSize_RecordsAndRethrows() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithOrderBy(o => o.Id).WithPage(1); + + Func act = () => ev.EvaluateQueryFailedAsync(spec); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateTopAsync_CombinedWithPagination_ThrowsInvalidOperationException() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithOrderBy(o => o.Id).WithPagination(1, 10); + + Func act = () => ev.EvaluateTopAsync(spec, 5); + + await act.Should().ThrowAsync(); + } + + [Fact] + public void QuerySpecification_FourArgConstructor_SetsOptions() + { + var spec = new QuerySpecification(new ValiFlowQuery(), asNoTracking: false, asSplitQuery: true); + + spec.AsNoTracking.Should().BeFalse(); + spec.AsSplitQuery.Should().BeTrue(); + } + + [Fact] + public void WithTop_AfterPageSize_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification().WithPageSize(10); + + Action act = () => spec.WithTop(5); + + act.Should().Throw(); + } + + [Fact] + public async Task EvaluateAnyAsync_NullFilterOnCustomSpecification_RecordsAndRethrows() + { + // BasicSpecification's own constructors never allow a null Filter (they either default to a new + // ValiFlowQuery or throw ArgumentNullException), so QuerySpecificationBuilder's + // Validation.ValidateFilterNotNull guard is only reachable via a custom ISpecification. + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + var spec = new RawQuerySpec { Filter = null! }; + + Func act = () => ev.EvaluateAnyAsync(spec); + + await act.Should().ThrowAsync(); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfMiscGapsTests.cs b/Vali-Flow.Tests/ValiFlowEfMiscGapsTests.cs new file mode 100644 index 0000000..803e50c --- /dev/null +++ b/Vali-Flow.Tests/ValiFlowEfMiscGapsTests.cs @@ -0,0 +1,213 @@ +using System.Numerics; +using FluentAssertions; +using Microsoft.Data.Sqlite; +using Microsoft.EntityFrameworkCore; +using Microsoft.Extensions.DependencyInjection; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Repository; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; +using Vali_Flow.Extensions; +using Vali_Flow.Interfaces.Evaluators.Read; +using Vali_Flow.Interfaces.Evaluators.Write; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Grab-bag covering: GenericRepository.SaveChangesAsync, ServiceCollectionExtensions.AddValiFlowEvaluator, +/// the dead decimal constant in Utils.Constants, the ExecuteNumericAggAsync double/float/long/fallback +/// branches (via EvaluateMinAsync/EvaluateMaxAsync), and the ExecuteTransactionAsync "reused existing +/// transaction" failure path (RunWithinExistingTransactionAsync's catch branch). +/// +public sealed class ValiFlowEfMiscGapsTests +{ + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + private static async Task CreateSeededContextAsync() + { + var ctx = CreateContext(); + ctx.Orders.AddRange( + new TestOrder { Id = 1, CustomerName = "Alice", Total = 150m, IsShipped = true, CreatedAt = new DateTime(2024, 1, 1) }, + new TestOrder { Id = 2, CustomerName = "Bob", Total = 320m, IsShipped = false, CreatedAt = new DateTime(2024, 2, 1) }, + new TestOrder { Id = 3, CustomerName = "Carol", Total = 80m, IsShipped = true, CreatedAt = new DateTime(2024, 3, 1) } + ); + await ctx.SaveChangesAsync(); + return ctx; + } + + private static BasicSpecification AllOrders() => new(new ValiFlowQuery()); + + // ── GenericRepository.SaveChangesAsync ──────────────────────────────────── + + [Fact] + public async Task GenericRepository_SaveChangesAsync_PersistsPendingChanges() + { + await using var ctx = CreateContext(); + var evaluator = new ValiFlowEvaluator(ctx); + var repo = new GenericRepository(evaluator, o => o.Id); + + ctx.Orders.Add(new TestOrder { Id = 1, CustomerName = "Alice", Total = 1m, IsShipped = false, CreatedAt = DateTime.UtcNow }); + await repo.SaveChangesAsync(); + + (await ctx.Orders.CountAsync()).Should().Be(1); + } + + // ── ServiceCollectionExtensions.AddValiFlowEvaluator ─────────────────────── + + [Fact] + public void AddValiFlowEvaluator_RegistersEvaluatorAndReadWriteInterfaces() + { + var services = new ServiceCollection(); + services.AddDbContext(o => o.UseInMemoryDatabase(Guid.NewGuid().ToString())); + services.AddValiFlowEvaluator(); + + using var provider = services.BuildServiceProvider(); + using var scope = provider.CreateScope(); + + var evaluator = scope.ServiceProvider.GetRequiredService>(); + var reader = scope.ServiceProvider.GetRequiredService>(); + var writer = scope.ServiceProvider.GetRequiredService>(); + + evaluator.Should().NotBeNull(); + reader.Should().BeSameAs(evaluator); + writer.Should().BeSameAs(evaluator); + } + + // Note: Utils.Constants.ZeroDecimal is unreferenced anywhere in production code and the class is + // `internal` (no InternalsVisibleTo to Vali-Flow.Tests), so its line is genuinely untestable dead + // code from this project without touching a .csproj — documented in the final report instead. + + // ── ExecuteNumericAggAsync — double/float/long branches + exotic fallback ─ + + [Fact] + public async Task EvaluateMinAsync_DoubleSelector_ReturnsMin() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMinAsync(AllOrders(), o => (double)o.Total); + + result.Should().Be(80d); + } + + [Fact] + public async Task EvaluateMinAsync_FloatSelector_ReturnsMin() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMinAsync(AllOrders(), o => (float)o.Total); + + result.Should().Be(80f); + } + + [Fact] + public async Task EvaluateMinAsync_LongSelector_ReturnsMin() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMinAsync(AllOrders(), o => (long)o.Total); + + result.Should().Be(80L); + } + + [Fact] + public async Task EvaluateMaxAsync_DoubleSelector_ReturnsMax() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMaxAsync(AllOrders(), o => (double)o.Total); + + result.Should().Be(320d); + } + + [Fact] + public async Task EvaluateMaxAsync_FloatSelector_ReturnsMax() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMaxAsync(AllOrders(), o => (float)o.Total); + + result.Should().Be(320f); + } + + [Fact] + public async Task EvaluateMaxAsync_LongSelector_ReturnsMax() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMaxAsync(AllOrders(), o => (long)o.Total); + + result.Should().Be(320L); + } + + [Fact] + public async Task EvaluateMinAsync_ExoticNumericSelector_FallsBackToInMemoryMin() + { + // BigInteger matches none of the five fast-path branches in ExecuteNumericAggAsync, + // exercising the materialize-and-compute-in-memory fallback. + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMinAsync(AllOrders(), o => (BigInteger)o.Total); + + result.Should().Be(new BigInteger(80)); + } + + [Fact] + public async Task EvaluateMaxAsync_ExoticNumericSelector_FallsBackToInMemoryMax() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMaxAsync(AllOrders(), o => (BigInteger)o.Total); + + result.Should().Be(new BigInteger(320)); + } + + [Fact] + public async Task EvaluateMinAsync_ExoticNumericSelector_EmptyResult_ReturnsZero() + { + await using var ctx = CreateContext(); + var ev = new ValiFlowEvaluator(ctx); + + var result = await ev.EvaluateMinAsync(AllOrders(), o => (BigInteger)o.Total); + + result.Should().Be(BigInteger.Zero); + } + + // ── ExecuteTransactionAsync — reused existing transaction, operations throw ── + + [Fact] + public async Task ExecuteTransactionAsync_ReusedExistingTransaction_OperationThrows_RecordsAndRethrows() + { + using var connection = new SqliteConnection("DataSource=:memory:"); + connection.Open(); + var options = new DbContextOptionsBuilder().UseSqlite(connection).Options; + await using var ctx = new TestDbContext(options); + await ctx.Database.EnsureCreatedAsync(); + + var ev = new ValiFlowEvaluator(ctx); + + // Begin a transaction manually so ExecuteTransactionAsync detects CurrentTransaction != null and + // takes the RunWithinExistingTransactionAsync branch instead of starting a new one. + await using var outerTx = await ctx.Database.BeginTransactionAsync(); + + Func act = () => ev.ExecuteTransactionAsync(() => throw new InvalidOperationException("boom")); + + await act.Should().ThrowAsync().WithMessage("boom"); + + // The evaluator must not have touched the outer transaction — it's still usable. + await outerTx.RollbackAsync(); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfQueryTests.cs b/Vali-Flow.Tests/ValiFlowEfQueryTests.cs index 74562eb..78d90f3 100644 --- a/Vali-Flow.Tests/ValiFlowEfQueryTests.cs +++ b/Vali-Flow.Tests/ValiFlowEfQueryTests.cs @@ -318,4 +318,26 @@ public async Task EvaluatePagedAsync_FilteredShipped_PaginationIsCorrect() paged.Items[0].CustomerName.Should().Be("Carol"); paged.Items[1].CustomerName.Should().Be("Alice"); } + + [Fact] + public async Task EvaluatePagedResultAsync_IsAliasOfEvaluatePagedAsync_SameResult() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var spec = new QuerySpecification( + new ValiFlowQuery().IsTrue(o => o.IsShipped)) + .WithOrderBy(o => o.Total) + .WithPagination(1, 2); + + var paged = await ev.EvaluatePagedResultAsync(spec); + + // Same data/behavior as EvaluatePagedAsync_FilteredShipped_PaginationIsCorrect — + // EvaluatePagedResultAsync is a pure alias kept for API symmetry with Vali-Flow.InMemory. + paged.TotalCount.Should().Be(3); + paged.TotalPages.Should().Be(2); + paged.Items.Should().HaveCount(2); + paged.Items[0].CustomerName.Should().Be("Carol"); + paged.Items[1].CustomerName.Should().Be("Alice"); + } } diff --git a/Vali-Flow.Tests/ValiFlowEfSpecificationBuilderTests.cs b/Vali-Flow.Tests/ValiFlowEfSpecificationBuilderTests.cs new file mode 100644 index 0000000..ca95853 --- /dev/null +++ b/Vali-Flow.Tests/ValiFlowEfSpecificationBuilderTests.cs @@ -0,0 +1,415 @@ +using System.Linq.Expressions; +using FluentAssertions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; +using Vali_Flow.Core.Utils; +using Vali_Flow.Interfaces.Options; +using Vali_Flow.Interfaces.Specification; +using Vali_Flow.Tests.Infrastructure; +using Vali_Flow.Tests.Models; +using Xunit; + +namespace Vali_Flow.Tests; + +/// +/// Minimal hand-rolled used to reach QuerySpecificationBuilder guard +/// branches that are unreachable through QuerySpecification's own fluent API (which keeps the conflicting +/// states mutually exclusive by construction) — e.g. both tracking flags true at once, or Top combined +/// with Page/PageSize on the same specification. +/// +internal sealed class RawQuerySpec : IQuerySpecification where T : class +{ + public ValiFlowQuery Filter { get; set; } = new(); + public IEnumerable>? Includes { get; set; } + public bool AsNoTracking { get; set; } = true; + public bool AsSplitQuery { get; set; } + public bool IgnoreQueryFilters { get; set; } + public bool IgnoreAutoIncludes { get; set; } + public bool AsNoTrackingWithIdentityResolution { get; set; } + public string? TagWith { get; set; } + public IEfOrderBy? OrderBy { get; set; } + public IEnumerable>? ThenBys { get; set; } + public int? Page { get; set; } + public int? PageSize { get; set; } + public int? Top { get; set; } + public ValiSort? ValiSort { get; set; } +} + +/// +/// Covers the fluent setters on BasicSpecification/QuerySpecification directly (most are never exercised +/// by evaluator-level tests because the defaults already satisfy most query paths), plus the +/// EfThenInclude/EfThenIncludeReference ApplyInclude methods and the QuerySpecificationBuilder guard +/// clauses (Top+Paging exclusivity, Page/PageSize must be set together, ThenBy without OrderBy, ValiSort +/// branch, and the actual Skip/Take application). +/// +public sealed class ValiFlowEfSpecificationBuilderTests +{ + private static TestDbContext CreateContext() => + new(new DbContextOptionsBuilder() + .UseInMemoryDatabase(Guid.NewGuid().ToString()) + .Options); + + private static async Task CreateSeededContextAsync() + { + var ctx = CreateContext(); + var customer = new TestCustomer { Id = 1, Name = "Acme" }; + ctx.Customers.Add(customer); + ctx.Orders.AddRange( + new TestOrder { Id = 1, CustomerName = "Alice", Total = 150m, IsShipped = true, CreatedAt = new DateTime(2024, 1, 1), CustomerId = 1 }, + new TestOrder { Id = 2, CustomerName = "Bob", Total = 320m, IsShipped = false, CreatedAt = new DateTime(2024, 2, 1), CustomerId = 1 }, + new TestOrder { Id = 3, CustomerName = "Carol", Total = 80m, IsShipped = true, CreatedAt = new DateTime(2024, 3, 1), CustomerId = 1 } + ); + await ctx.SaveChangesAsync(); + return ctx; + } + + // ── BasicSpecification fluent setters ───────────────────────────────────── + + [Fact] + public void WithFilter_ReplacesFilter() + { + var spec = new BasicSpecification(); + var newFilter = new ValiFlowQuery().IsTrue(o => o.IsShipped); + + spec.WithFilter(newFilter); + + spec.Filter.Should().BeSameAs(newFilter); + } + + [Fact] + public void WithFilter_Null_ThrowsArgumentNullException() + { + var spec = new BasicSpecification(); + + Action act = () => spec.WithFilter(null!); + + act.Should().Throw(); + } + + [Fact] + public void WithAsSplitQuery_SetsFlag() + { + var spec = new BasicSpecification().WithAsSplitQuery(true); + + spec.AsSplitQuery.Should().BeTrue(); + } + + [Fact] + public void WithIgnoreQueryFilters_SetsFlag() + { + var spec = new BasicSpecification().WithIgnoreQueryFilters(true); + + spec.IgnoreQueryFilters.Should().BeTrue(); + } + + [Fact] + public void WithIgnoreAutoIncludes_SetsFlag() + { + var spec = new BasicSpecification().WithIgnoreAutoIncludes(true); + + spec.IgnoreAutoIncludes.Should().BeTrue(); + } + + [Fact] + public void WithAsNoTrackingWithIdentityResolution_Enabled_DisablesAsNoTracking() + { + var spec = new BasicSpecification().WithAsNoTrackingWithIdentityResolution(true); + + spec.AsNoTrackingWithIdentityResolution.Should().BeTrue(); + spec.AsNoTracking.Should().BeFalse(); + } + + [Fact] + public void WithTagWith_SetsTag() + { + var spec = new BasicSpecification().WithTagWith("my-tag"); + + spec.TagWith.Should().Be("my-tag"); + } + + [Fact] + public void AddThenInclude_Null_ThrowsArgumentNullException() + { + var spec = new BasicSpecification(); + + Action act = () => spec.AddThenInclude(null!, i => i.ProductName); + + act.Should().Throw(); + } + + [Fact] + public void AddThenIncludeReference_Null_ThrowsArgumentNullException() + { + var spec = new BasicSpecification(); + + Action act = () => spec.AddThenIncludeReference(null!, c => c.Name); + + act.Should().Throw(); + } + + [Fact] + public async Task AddThenInclude_AppliedToQuery_LoadsNestedCollectionNavigation() + { + // Root = TestCustomer: Include(Orders) [collection] .ThenInclude(Items) [collection] — two distinct + // navigations with no cycle back to the root type, unlike Order->Customer->Orders. + await using var ctx = CreateContext(); + ctx.Customers.Add(new TestCustomer + { + Id = 1, Name = "Acme", + Orders = + { + new TestOrder + { + Id = 1, CustomerName = "Alice", Total = 150m, IsShipped = true, CreatedAt = DateTime.UtcNow, + Items = { new TestOrderItem { Id = 1, OrderId = 1, ProductName = "Widget", UnitPrice = 9.99m } } + } + } + }); + await ctx.SaveChangesAsync(); + ctx.ChangeTracker.Clear(); + + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification(new ValiFlowQuery().EqualTo(c => c.Id, 1)) + .AddThenInclude>(c => c.Orders, o => o.Items); + + var query = await evaluator.EvaluateQueryAsync(spec); + var result = query.ToList(); + + result.Should().ContainSingle(); + result[0].Orders.Should().ContainSingle(); + result[0].Orders.First().Items.Should().ContainSingle(i => i.ProductName == "Widget"); + } + + [Fact] + public async Task AddThenIncludeReference_AppliedToQuery_LoadsNestedReferenceNavigation() + { + // Root = TestOrderItem: Include(Order) [reference] .ThenInclude(Customer) [reference] — two distinct + // reference navigations with no cycle. + await using var ctx = await CreateSeededContextAsync(); + var order = await ctx.Orders.FirstAsync(o => o.Id == 1); + ctx.OrderItems.Add(new TestOrderItem { Id = 1, OrderId = order.Id, ProductName = "Widget", UnitPrice = 9.99m, Order = order }); + await ctx.SaveChangesAsync(); + ctx.ChangeTracker.Clear(); + + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification(new ValiFlowQuery().EqualTo(i => i.Id, 1)) + .AddThenIncludeReference(i => i.Order, o => o.Customer); + + var query = await evaluator.EvaluateQueryAsync(spec); + var result = query.ToList(); + + result.Should().ContainSingle(); + result[0].Order.Customer.Should().NotBeNull(); + result[0].Order.Customer!.Name.Should().Be("Acme"); + } + + // ── QuerySpecification guard clauses ────────────────────────────────────── + + [Fact] + public void WithOrderBy_AfterValiSort_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification().WithValiSort(new ValiSort()); + + Action act = () => spec.WithOrderBy(o => o.Id); + + act.Should().Throw(); + } + + [Fact] + public void AddThenBy_WithoutOrderBy_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification(); + + Action act = () => spec.AddThenBy(o => o.Id); + + act.Should().Throw(); + } + + [Fact] + public void AddThenBy_AfterValiSort_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification() + .WithOrderBy(o => o.Id); + // Force ValiSort onto a fresh spec, then try AddThenBy on one already carrying OrderBy + a direct + // ValiSort would be contradictory to construct normally, so validate via AddThenBys with ValiSort set. + var sortedSpec = new QuerySpecification().WithValiSort(new ValiSort()); + + Action act = () => sortedSpec.AddThenBy(o => o.Id); + + act.Should().Throw(); + } + + [Fact] + public void AddThenBys_WithoutOrderBy_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification(); + + Action act = () => spec.AddThenBys(new System.Linq.Expressions.Expression>[] { o => o.Id }); + + act.Should().Throw(); + } + + [Fact] + public void AddThenBys_AfterValiSort_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification().WithValiSort(new ValiSort()); + + Action act = () => spec.AddThenBys(new System.Linq.Expressions.Expression>[] { o => o.Id }); + + act.Should().Throw(); + } + + [Fact] + public void AddThenBys_WithOrderBySet_AddsAllExpressions() + { + var spec = new QuerySpecification() + .WithOrderBy(o => o.Id) + .AddThenBys(new System.Linq.Expressions.Expression>[] { o => o.CustomerName }); + + spec.ThenBys.Should().ContainSingle(); + } + + [Fact] + public void WithPage_AfterTop_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification().WithTop(5); + + Action act = () => spec.WithPage(1); + + act.Should().Throw(); + } + + [Fact] + public void WithPageSize_AfterTop_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification().WithTop(5); + + Action act = () => spec.WithPageSize(10); + + act.Should().Throw(); + } + + [Fact] + public void WithValiSort_AfterOrderBy_ThrowsInvalidOperationException() + { + var spec = new QuerySpecification().WithOrderBy(o => o.Id); + + Action act = () => spec.WithValiSort(new ValiSort()); + + act.Should().Throw(); + } + + [Fact] + public void WithValiSort_Null_ThrowsArgumentNullException() + { + var spec = new QuerySpecification(); + + Action act = () => spec.WithValiSort(null!); + + act.Should().Throw(); + } + + // ── QuerySpecificationBuilder guards (exercised through the evaluator) ──── + + [Fact] + public async Task EvaluateQueryAsync_AsNoTrackingAndIdentityResolutionBothTrue_ThrowsInvalidOperationException() + { + // QuerySpecification's own fluent setters keep AsNoTracking and AsNoTrackingWithIdentityResolution + // mutually exclusive by construction, so this guard in QuerySpecificationBuilder is only reachable + // through a custom ISpecification implementation that sets both independently. + await using var ctx = await CreateSeededContextAsync(); + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new RawQuerySpec + { + AsNoTracking = true, + AsNoTrackingWithIdentityResolution = true, + OrderBy = new global::Vali_Flow.Classes.Options.EfOrderBy(o => o.Id, true) + }; + + Func act = () => evaluator.EvaluateQueryAsync(spec); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateQueryAsync_TopCombinedWithPaging_ThrowsInvalidOperationException() + { + // WithTop and WithPagination are mutually exclusive via QuerySpecification's own guards, so the + // QuerySpecificationBuilder.EnsureTopNotCombinedWithPaging guard is only reachable via a custom spec. + await using var ctx = await CreateSeededContextAsync(); + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new RawQuerySpec { Top = 5, Page = 1, PageSize = 10 }; + + Func act = () => evaluator.EvaluateQueryAsync(spec); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateQueryAsync_PageSetWithoutPageSize_ThrowsInvalidOperationException() + { + // WithPage and WithPageSize can be called independently on QuerySpecification, unlike WithPagination + // — this reaches QuerySpecificationBuilder.EnsurePageAndPageSizeSetTogether through the public API. + await using var ctx = await CreateSeededContextAsync(); + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification().WithOrderBy(o => o.Id).WithPage(1); + + Func act = () => evaluator.EvaluateQueryAsync(spec); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateQueryAsync_ThenBysWithoutOrderBy_ThrowsInvalidOperationException() + { + // QuerySpecification.AddThenBy already requires OrderBy to be set first, so this ApplyOrdering + // guard in QuerySpecificationBuilder is only reachable via a custom spec with ThenBys populated + // but OrderBy left null. + await using var ctx = await CreateSeededContextAsync(); + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new RawQuerySpec + { + ThenBys = new List> + { + new global::Vali_Flow.Classes.Options.EfOrderThenBy(o => o.Id, true) + } + }; + + Func act = () => evaluator.EvaluateQueryAsync(spec); + + await act.Should().ThrowAsync(); + } + + [Fact] + public async Task EvaluateQueryAsync_ValiSortSet_AppliesValiSortOrdering() + { + await using var ctx = await CreateSeededContextAsync(); + var evaluator = new ValiFlowEvaluator(ctx); + var sort = new ValiSort(); + sort.By(o => o.Total, descending: true); + var spec = new QuerySpecification().WithValiSort(sort); + + var query = await evaluator.EvaluateQueryAsync(spec); + var results = query.ToList(); + + results.Select(o => o.Total).Should().BeInDescendingOrder(); + } + + [Fact] + public async Task EvaluateQueryAsync_PageAndPageSizeWithOrdering_AppliesSkipTake() + { + await using var ctx = await CreateSeededContextAsync(); + var evaluator = new ValiFlowEvaluator(ctx); + var spec = new QuerySpecification() + .WithOrderBy(o => o.Id) + .WithPagination(2, 1); + + var query = await evaluator.EvaluateQueryAsync(spec); + var results = query.ToList(); + + results.Should().ContainSingle(); + results[0].Id.Should().Be(2); + } +} diff --git a/Vali-Flow.Tests/ValiFlowEfWriteTests.cs b/Vali-Flow.Tests/ValiFlowEfWriteTests.cs index fa54008..07b1415 100644 --- a/Vali-Flow.Tests/ValiFlowEfWriteTests.cs +++ b/Vali-Flow.Tests/ValiFlowEfWriteTests.cs @@ -168,6 +168,74 @@ public async Task UpsertAsync_EntityExists_UpdatesValues() result.Total.Should().Be(500m); } + // ── UpsertRangeAsync — duplicate keys within the same batch ────────────── + + [Fact] + public async Task UpsertRangeAsync_DuplicateKeysNotYetInDatabase_InsertsOnlyOne() + { + await using var ctx = CreateContext(); + var ev = new ValiFlowEvaluator(ctx); + + // Two incoming entities share the same business key (CustomerName) and neither + // exists in the DB yet. A correct upsert should collapse them into a single row + // (last one wins), not insert both. + var entities = new[] + { + new TestOrder { CustomerName = "Dup", Total = 10m, IsShipped = false, CreatedAt = DateTime.UtcNow }, + new TestOrder { CustomerName = "Dup", Total = 20m, IsShipped = true, CreatedAt = DateTime.UtcNow } + }; + + await ev.UpsertRangeAsync(entities, o => o.CustomerName); + + var rows = await ctx.Orders.AsNoTracking().Where(o => o.CustomerName == "Dup").ToListAsync(); + rows.Should().HaveCount(1); + rows[0].Total.Should().Be(20m); // last occurrence in the batch wins + } + + [Fact] + public async Task UpsertRangeAsync_DuplicateKeysAgainstExistingRow_UpdatesOnceWithLastValue() + { + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + // Alice (Id=1) already exists. Two incoming entities target her by key; the + // batch should still result in exactly one row for Alice with the last value applied. + var entities = new[] + { + new TestOrder { Id = 1, CustomerName = "Alice", Total = 111m, IsShipped = false, CreatedAt = DateTime.UtcNow }, + new TestOrder { Id = 1, CustomerName = "Alice", Total = 222m, IsShipped = true, CreatedAt = DateTime.UtcNow } + }; + + await ev.UpsertRangeAsync(entities, o => o.CustomerName); + + var rows = await ctx.Orders.AsNoTracking().Where(o => o.CustomerName == "Alice").ToListAsync(); + rows.Should().HaveCount(1); + rows[0].Total.Should().Be(222m); + } + + [Fact] + public async Task UpsertRangeAsync_IncomingEntityHasDifferentIdThanExistingRow_UpdatesInPlaceWithoutThrowing() + { + // Regression test: callers upserting by a business key (CustomerName here) normally build a + // fresh entity per request and have no reason to know -- or preserve -- the existing row's PK. + // Before the PartitionUpsertRange fix, EF's CurrentValues.SetValues(entity) tried to overwrite + // the tracked entity's Id with the incoming (unrelated, freshly-generated) Id and threw + // InvalidOperationException ("... is part of a key and so cannot be modified"), found while + // stress-testing UpsertRangeAsync with realistic upsert payloads (Vali-Flow EF Core stress run). + await using var ctx = await CreateSeededContextAsync(); + var ev = new ValiFlowEvaluator(ctx); + + var incoming = new TestOrder { Id = 999, CustomerName = "Alice", Total = 999m, IsShipped = true, CreatedAt = DateTime.UtcNow }; + + var act = async () => await ev.UpsertRangeAsync(new[] { incoming }, o => o.CustomerName); + await act.Should().NotThrowAsync(); + + var rows = await ctx.Orders.AsNoTracking().Where(o => o.CustomerName == "Alice").ToListAsync(); + rows.Should().HaveCount(1); + rows[0].Id.Should().Be(1); // existing PK preserved, not overwritten by the incoming Id=999 + rows[0].Total.Should().Be(999m); // non-key fields still applied + } + // ── SaveChangesAsync — deferred ─────────────────────────────────────────── [Fact] diff --git a/Vali-Flow/AssemblyInfo.cs b/Vali-Flow/AssemblyInfo.cs new file mode 100644 index 0000000..a9faba7 --- /dev/null +++ b/Vali-Flow/AssemblyInfo.cs @@ -0,0 +1,3 @@ +using System.Runtime.CompilerServices; + +[assembly: InternalsVisibleTo("Vali-Flow.Tests")] diff --git a/Vali-Flow/Classes/Evaluators/BulkUpsertRetryPolicy.cs b/Vali-Flow/Classes/Evaluators/BulkUpsertRetryPolicy.cs new file mode 100644 index 0000000..c0f3648 --- /dev/null +++ b/Vali-Flow/Classes/Evaluators/BulkUpsertRetryPolicy.cs @@ -0,0 +1,178 @@ +namespace Vali_Flow.Classes.Evaluators; + +/// +/// Generic transient-failure retry for bulk upsert/update operations, covering the concurrency pitfalls +/// EFCore.BulkExtensions itself documents for the most common relational providers: +/// +/// PostgreSQL / MySQL: matching by BulkConfig.UpdateByProperties (instead of +/// the primary key) makes the library create then drop a temporary unique index/constraint around the merge +/// via CREATE INDEX CONCURRENTLY (PostgreSQL) or an equivalent DDL statement (MySQL), which serializes +/// against *any other transaction on the same table* — not just ones touching the same rows/columns. A +/// stress run sweeping the shared-key pool from 15 up to 10,000 distinct keys found the retry activation +/// rate unchanged across every pool size, ruling out key collision as the cause: this is table-level DDL +/// contention proportional to concurrent request rate on that table, surfacing as e.g. PostgreSQL's +/// 42704 "index ... does not exist" when one caller's DDL interleaves with another's. +/// SQL Server: the library's own README documents deadlocks as a known concurrency +/// issue for bulk merge operations (see upstream issue #46) — the server picks a victim transaction and kills +/// it with "Transaction (Process ID ...) was deadlocked ... and has been chosen as the deadlock victim", +/// independent of the temp-table mechanism above (SQL Server's temp table names are randomized by default, +/// so they don't collide the way Postgres/MySQL's deterministic names do). +/// SQLite: file-level write serialization means any concurrent writer (including a +/// second process) hitting the same database file while a bulk operation holds its write lock fails with +/// SQLITE_BUSY "database is locked" — a classic transient condition SQLite itself expects callers to +/// retry. +/// +/// These are the four most-used relational engines this ecosystem targets (see Vali-Flow.Sql's +/// dialect support); Oracle is deliberately not covered here — it is supported by EFCore.BulkExtensions +/// but is a materially less common deployment target, and its concurrency failure wording hasn't been +/// characterized against this specific race. +/// The in-process gate (see ValiFlowEvaluator.Write.cs, +/// GetBulkUpsertGate/RunGatedBulkUpsertAsync) already serializes same-process callers for the +/// first case, but neither case is covered once a second process (another instance of the API) is involved — +/// this retry is the generic, provider-agnostic fallback for that remaining window, for whichever of the +/// supported engines is in use. +/// +/// +/// Deliberately detects transiency by inspecting the exception message chain for markers of these specific +/// failure modes, not by referencing a provider-specific exception type (Npgsql/MySqlConnector/ +/// Microsoft.Data.SqlClient) — Vali-Flow has no package dependency on any ADO.NET provider and +/// this keeps it that way. +/// +internal static class BulkUpsertRetryPolicy +{ + /// + /// Default maximum attempts (1 initial try + up to 11 retries). History, measured against the real + /// cross-process scenario this retry targets (2 API instances, 50 req/s combined, 15 shared business + /// keys, BulkInsertOrUpdateAsync matching by a custom key): + /// + /// 4 attempts (~450ms budget): ~2% of requests (8/405) exhausted retries and propagated a 500. + /// 7 attempts (~2.4s budget): down to 0.12% (1/855) — real improvement, not zero. + /// 12 attempts (~5.4s budget, current): chosen to push further into this specific + /// artificially-high-contention benchmark (15 keys shared by 2 processes at a sustained 50 req/s is a + /// deliberately narrow pool, not representative of typical traffic). Zero residual failure under this + /// exact scenario is not guaranteed by construction — the race is a queue, not a fixed number of + /// contenders, so no finite retry budget can offer a 0% proof, only diminishing residual probability at + /// the cost of added worst-case latency for the caller stuck re-trying. + /// + /// + internal const int DefaultMaxAttempts = 12; + + /// Base delay for the exponential backoff between retries. + internal static readonly TimeSpan DefaultBaseDelay = TimeSpan.FromMilliseconds(50); + + /// + /// Upper bound on any single computed delay, so backoff never grows unbounded. Raised alongside + /// — see that constant's remarks for the measured rationale. + /// + internal static readonly TimeSpan DefaultMaxDelay = TimeSpan.FromMilliseconds(900); + + /// Upper bound (exclusive) of the random jitter added to each delay, to avoid a thundering herd of retries. + internal const int DefaultJitterMs = 50; + + /// Base of the exponential backoff growth (delay doubles on each successive retry). + private const double ExponentialBackoffBase = 2; + + // Substrings observed in the provider error message chain for the two concurrency failure modes above. + private static readonly string[] TransientMarkers = + { + // PostgreSQL / MySQL — temp unique index/constraint race around a custom UpdateByProperties match. + "tempUniqueIndex", // the deterministic name EFCore.BulkExtensions gives the object it creates/drops + "tempUniqueConstraint", + "does not exist", // PostgreSQL 42704 — one caller dropped the index between another's CREATE and its use + "doesn't exist", // MySQL wording for the equivalent race + "unknown table", + + // SQL Server — deadlock victim on the bulk merge (documented upstream, EFCore.BulkExtensions issue #46). + "deadlock", // covers both "was deadlocked" and "deadlock victim" wording + "deadlocked", + + // SQLite — SQLITE_BUSY: file-level write lock held by a concurrent writer (another process or thread). + "database is locked", + "sqlite_busy" + }; + + /// + /// Walks the exception's chain looking for a message matching one + /// of . Returns false for anything else — this must stay narrow: + /// a real constraint violation, a bad connection string, or any other failure should propagate immediately, + /// not be silently retried and delayed. + /// + internal static bool IsTransientTempIndexFailure(Exception? ex) + { + for (var current = ex; current != null; current = current.InnerException) + { + var message = current.Message; + if (string.IsNullOrEmpty(message)) continue; + + foreach (var marker in TransientMarkers) + { + if (message.Contains(marker, StringComparison.OrdinalIgnoreCase)) + return true; + } + } + + return false; + } + + /// + /// Runs , retrying on failures classified as transient by + /// (defaults to ), with exponential + /// backoff + jitter between attempts. Non-transient exceptions, and the last attempt's exception once + /// is exhausted, propagate unchanged — this never swallows a real failure. + /// + /// The operation to run. Invoked at least once. + /// + /// Checked before every attempt and honored during the backoff delay via ; + /// an from either path propagates immediately without being retried. + /// + /// + /// Optional callback invoked right before each retry delay, with the 1-based attempt number that just + /// failed and the exception that triggered the retry — used by the caller to tag diagnostics. + /// + /// Predicate deciding whether an exception should be retried. Defaults to . + /// Maximum total attempts, including the first. Must be at least 1. + /// Base delay for the exponential backoff (attempt 1 waits ~baseDelay, attempt 2 ~2x, etc.). + /// Upper bound applied to every computed delay before jitter is added. + internal static async Task ExecuteAsync( + Func operation, + CancellationToken cancellationToken, + Action? onRetry = null, + Func? isTransient = null, + int maxAttempts = DefaultMaxAttempts, + TimeSpan? baseDelay = null, + TimeSpan? maxDelay = null) + { + if (operation == null) throw new ArgumentNullException(nameof(operation)); + if (maxAttempts < 1) throw new ArgumentOutOfRangeException(nameof(maxAttempts), "maxAttempts must be at least 1."); + + isTransient ??= IsTransientTempIndexFailure; + var effectiveBaseDelay = baseDelay ?? DefaultBaseDelay; + var effectiveMaxDelay = maxDelay ?? DefaultMaxDelay; + + for (var attempt = 1; ; attempt++) + { + cancellationToken.ThrowIfCancellationRequested(); + + try + { + await operation().ConfigureAwait(false); + return; + } + catch (OperationCanceledException) + { + throw; + } + catch (Exception ex) when (attempt < maxAttempts && isTransient(ex)) + { + onRetry?.Invoke(attempt, ex); + + var exponential = effectiveBaseDelay.TotalMilliseconds * Math.Pow(ExponentialBackoffBase, attempt - 1); + var capped = Math.Min(exponential, effectiveMaxDelay.TotalMilliseconds); + var jitter = Random.Shared.Next(0, DefaultJitterMs); + var delay = TimeSpan.FromMilliseconds(capped + jitter); + + await Task.Delay(delay, cancellationToken).ConfigureAwait(false); + } + } + } +} diff --git a/Vali-Flow/Classes/Evaluators/QuerySpecificationBuilder.cs b/Vali-Flow/Classes/Evaluators/QuerySpecificationBuilder.cs new file mode 100644 index 0000000..d0b97be --- /dev/null +++ b/Vali-Flow/Classes/Evaluators/QuerySpecificationBuilder.cs @@ -0,0 +1,169 @@ +using System.Linq.Expressions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Core.Builder; +using Vali_Flow.Interfaces.Options; +using Vali_Flow.Interfaces.Specification; +using Vali_Flow.Utils; + +namespace Vali_Flow.Classes.Evaluators; + +/// +/// Translates an / into an EF Core +/// — filter, includes, tracking/split-query hints, ordering and pagination. +/// Extracted from so query-construction logic (a single, self-contained +/// responsibility) does not share state or private helpers with the read/write/aggregate operations that +/// consume it. +/// +internal sealed class QuerySpecificationBuilder where T : class +{ + private readonly DbContext _dbContext; + + public QuerySpecificationBuilder(DbContext dbContext) + { + _dbContext = dbContext; + } + + public IQueryable BuildBasicQuery(ISpecification specification, bool negateCondition = false) + { + IQueryable query = _dbContext.Set(); + + query = ApplyIgnoreQueryFilters(query, specification.IgnoreQueryFilters); + query = ApplyIgnoreAutoIncludes(query, specification.IgnoreAutoIncludes); + query = ApplyWhere(query, specification.Filter, negateCondition); + + if (specification.AsNoTracking && specification.AsNoTrackingWithIdentityResolution) + throw new InvalidOperationException( + "AsNoTracking and AsNoTrackingWithIdentityResolution are mutually exclusive. " + + "Use WithAsNoTracking(false) before calling WithAsNoTrackingWithIdentityResolution(true)."); + + query = ApplyAsNoTracking(query, specification.AsNoTracking); + query = ApplyAsNoTrackingWithIdentityResolution(query, specification.AsNoTrackingWithIdentityResolution); + query = ApplyIncludes(query, specification.Includes); + query = ApplyAsSplitQuery(query, specification.AsSplitQuery); + query = ApplyTagWith(query, specification.TagWith); + + return query; + } + + public IQueryable BuildQuery(IQuerySpecification specification, bool negateFilter = false) + { + ValidatePaginationAndOrdering(specification); + + IQueryable query = BuildBasicQuery(specification, negateFilter); + query = ApplyOrdering(query, specification); + query = ApplyPagination(query, specification); + return query; + } + + private static void ValidatePaginationAndOrdering(IQuerySpecification specification) + { + EnsureTopNotCombinedWithPaging(specification); + EnsurePageAndPageSizeSetTogether(specification); + EnsurePaginationHasOrdering(specification); + } + + private static void EnsureTopNotCombinedWithPaging(IQuerySpecification specification) + { + if (specification.Top.HasValue && (specification.Page.HasValue || specification.PageSize.HasValue)) + throw new InvalidOperationException( + "Cannot combine Top with Page/PageSize pagination on the same specification. Use one or the other."); + } + + private static void EnsurePageAndPageSizeSetTogether(IQuerySpecification specification) + { + bool pageSetWithoutPageSize = specification.Page.HasValue && specification.Page.Value > 0 && + (!specification.PageSize.HasValue || specification.PageSize.Value <= 0); + bool pageSizeSetWithoutPage = specification.PageSize.HasValue && specification.PageSize.Value > 0 && + (!specification.Page.HasValue || specification.Page.Value <= 0); + if (pageSetWithoutPageSize || pageSizeSetWithoutPage) + throw new InvalidOperationException( + "Both Page and PageSize must be set together. Use WithPagination(page, pageSize)."); + } + + private static void EnsurePaginationHasOrdering(IQuerySpecification specification) + { + bool hasPagination = specification.Page.HasValue || specification.PageSize.HasValue; + bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; + if (hasPagination && !hasOrdering) + throw new InvalidOperationException( + "Pagination requires an ordering to produce deterministic results. " + + "Set OrderBy or ValiSort on the specification before enabling pagination."); + } + + public IQueryable ApplyOrdering(IQueryable query, IQuerySpecification specification) + { + if (specification.ValiSort != null) + return specification.ValiSort.Apply(query); + + if (specification.OrderBy == null) + { + if (specification.ThenBys != null) + throw new InvalidOperationException( + "ThenBy requires a primary OrderBy. Set OrderBy on the specification before adding ThenBy expressions."); + return query; + } + + IOrderedQueryable orderedQuery = specification.OrderBy.ApplyOrderBy(query); + + if (specification.ThenBys != null) + { + foreach (var thenBy in specification.ThenBys) + orderedQuery = thenBy.ApplyThenBy(orderedQuery); + } + + return orderedQuery; + } + + private IQueryable ApplyWhere(IQueryable query, ValiFlowQuery filter, bool negateCondition = false) + { + Validation.ValidateFilterNotNull(filter); + + Expression> condition = negateCondition ? filter.BuildNegated() : filter.BuildWithGlobal(); + return query.Where(condition); + } + + private IQueryable ApplyPagination(IQueryable query, IQuerySpecification specification) + { + if (specification is { Page: not null, PageSize: not null }) + { + int skip = (specification.Page.Value - Constants.One) * specification.PageSize.Value; + int take = specification.PageSize.Value; + query = query.Skip(skip).Take(take); + } + else if (specification.Top != null) + { + query = query.Take(specification.Top.Value); + } + + return query; + } + + private IQueryable ApplyAsNoTracking(IQueryable query, bool asNoTracking = true) => asNoTracking ? query.AsNoTracking() : query; + + private IQueryable ApplyAsNoTrackingWithIdentityResolution(IQueryable query, bool apply) + => apply ? query.AsNoTrackingWithIdentityResolution() : query; + + private IQueryable ApplyTagWith(IQueryable query, string? tag) + => tag != null ? query.TagWith(tag) : query; + + private IQueryable ApplyIgnoreAutoIncludes(IQueryable query, bool apply) + => apply ? query.IgnoreAutoIncludes() : query; + + private IQueryable ApplyIgnoreQueryFilters(IQueryable query, bool ignoreQueryFilters = false) => + ignoreQueryFilters ? query.IgnoreQueryFilters() : query; + + private IQueryable ApplyAsSplitQuery(IQueryable query, bool asSplitQuery = false) => asSplitQuery ? query.AsSplitQuery() : query; + + private IQueryable ApplyIncludes(IQueryable query, IEnumerable>? includes) + { + if (includes != null) + { + foreach (var include in includes) + { + query = include.ApplyInclude(query); + } + } + + return query; + } +} diff --git a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Bridge.cs b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Bridge.cs index 9da8f4c..b3f7b83 100644 --- a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Bridge.cs +++ b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Bridge.cs @@ -53,6 +53,8 @@ async Task IQueryAggregator.EvaluateMinAsync( IQueryable query = _dbContext.Set().AsNoTracking(); if (filter != null) query = query.Where(filter.Build()); if (!await query.AnyAsync(cancellationToken)) + // TResult : INumber is effectively always a value type in practice (int, double, decimal, ...), + // so default(TResult) here is a real number (e.g. 0), not a hidden null — see XML doc on the interface. return default(TResult)!; return await query.MinAsync(selector, cancellationToken); } diff --git a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Read.cs b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Read.cs index c8591cb..3c1594c 100644 --- a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Read.cs +++ b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Read.cs @@ -1,5 +1,7 @@ +using System.Diagnostics; using System.Linq.Expressions; using Microsoft.EntityFrameworkCore; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Interfaces.Specification; using Vali_Flow.Core.Builder; using Vali_Flow.Models; @@ -38,9 +40,21 @@ public async Task EvaluateAnyAsync( ) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - IQueryable query = BuildBasicQuery(specification); - return await ExecuteWithExceptionHandlingAsync(() => query.AnyAsync(cancellationToken), - nameof(EvaluateAnyAsync)); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateAnyAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + IQueryable query = BuildBasicQuery(specification); + return await ExecuteWithExceptionHandlingAsync(() => query.AnyAsync(cancellationToken), + nameof(EvaluateAnyAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -56,9 +70,21 @@ public async Task EvaluateCountAsync( ) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - IQueryable query = BuildBasicQuery(specification); - return await ExecuteWithExceptionHandlingAsync(() => query.CountAsync(cancellationToken), - nameof(EvaluateCountAsync)); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateCountAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + IQueryable query = BuildBasicQuery(specification); + return await ExecuteWithExceptionHandlingAsync(() => query.CountAsync(cancellationToken), + nameof(EvaluateCountAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -75,9 +101,21 @@ public async Task EvaluateCountAsync( ) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - var query = BuildBasicQuery(specification, true); - return await ExecuteWithExceptionHandlingAsync(() => query.FirstOrDefaultAsync(cancellationToken), - nameof(EvaluateGetFirstFailedAsync)); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateGetFirstFailedAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + var query = BuildBasicQuery(specification, true); + return await ExecuteWithExceptionHandlingAsync(() => query.FirstOrDefaultAsync(cancellationToken), + nameof(EvaluateGetFirstFailedAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -93,9 +131,21 @@ public async Task EvaluateCountAsync( ) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - var query = BuildBasicQuery(specification); - return await ExecuteWithExceptionHandlingAsync(() => query.FirstOrDefaultAsync(cancellationToken), - nameof(EvaluateGetFirstAsync)); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateGetFirstAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + var query = BuildBasicQuery(specification); + return await ExecuteWithExceptionHandlingAsync(() => query.FirstOrDefaultAsync(cancellationToken), + nameof(EvaluateGetFirstAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -108,8 +158,22 @@ public async Task EvaluateCountAsync( public Task> EvaluateQueryFailedAsync(IQuerySpecification specification) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - IQueryable query = BuildQuery(specification, negateFilter: true); - return Task.FromResult(query); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateQueryFailedAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + activity?.SetTag("vali_flow.has_pagination", specification.Page.HasValue || specification.PageSize.HasValue); + activity?.SetTag("vali_flow.has_order_by", specification.OrderBy != null || specification.ValiSort != null); + IQueryable query = BuildQuery(specification, negateFilter: true); + return Task.FromResult(query); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -122,8 +186,22 @@ public Task> EvaluateQueryFailedAsync(IQuerySpecification speci public Task> EvaluateQueryAsync(IQuerySpecification specification) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - IQueryable query = BuildQuery(specification); - return Task.FromResult(query); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateQueryAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + activity?.SetTag("vali_flow.has_pagination", specification.Page.HasValue || specification.PageSize.HasValue); + activity?.SetTag("vali_flow.has_order_by", specification.OrderBy != null || specification.ValiSort != null); + IQueryable query = BuildQuery(specification); + return Task.FromResult(query); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -197,25 +275,41 @@ public async Task> EvaluateDistinctAsync( ) where TKey : notnull { if (specification == null) throw new ArgumentNullException(nameof(specification)); - if (specification.Page.HasValue != specification.PageSize.HasValue) - throw new InvalidOperationException("Both Page and PageSize must be set together, or neither."); - if (selector == null) throw new ArgumentNullException(nameof(selector)); - bool hasPagination = specification.PageSize.HasValue || specification.Top.HasValue; - bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; - if (hasPagination && !hasOrdering) - throw new InvalidOperationException("Pagination requires an ordering."); - Func keySelectorFn = selector.Compile(); - IQueryable query = BuildBasicQuery(specification); - query = ApplyOrdering(query, specification); - List items = await query.ToListAsync(cancellationToken); - IEnumerable result = items.GroupBy(keySelectorFn).Select(g => g.First()); - // Pagination applied AFTER grouping so it operates on distinct groups, not raw rows - if (specification is { Page: not null, PageSize: not null }) - result = result.Skip((specification.Page.Value - Constants.One) * specification.PageSize.Value) - .Take(specification.PageSize.Value); - else if (specification.Top != null) - result = result.Take(specification.Top.Value); - return result; + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateDistinctAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + if (specification.Page.HasValue != specification.PageSize.HasValue) + throw new InvalidOperationException("Both Page and PageSize must be set together, or neither."); + if (selector == null) throw new ArgumentNullException(nameof(selector)); + bool hasPagination = specification.PageSize.HasValue || specification.Top.HasValue; + bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; + if (hasPagination && !hasOrdering) + throw new InvalidOperationException("Pagination requires an ordering."); + + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + activity?.SetTag("vali_flow.has_pagination", hasPagination); + activity?.SetTag("vali_flow.has_order_by", hasOrdering); + + Func keySelectorFn = selector.Compile(); + IQueryable query = BuildBasicQuery(specification); + query = ApplyOrdering(query, specification); + List items = await query.ToListAsync(cancellationToken); + IEnumerable result = items.GroupBy(keySelectorFn).Select(g => g.First()); + // Pagination applied AFTER grouping so it operates on distinct groups, not raw rows + if (specification is { Page: not null, PageSize: not null }) + result = result.Skip((specification.Page.Value - Constants.One) * specification.PageSize.Value) + .Take(specification.PageSize.Value); + else if (specification.Top != null) + result = result.Take(specification.Top.Value); + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -237,27 +331,43 @@ public async Task> EvaluateDuplicatesAsync( ) where TKey : notnull { if (specification == null) throw new ArgumentNullException(nameof(specification)); - if (specification.Page.HasValue != specification.PageSize.HasValue) - throw new InvalidOperationException("Both Page and PageSize must be set together, or neither."); - if (selector == null) throw new ArgumentNullException(nameof(selector)); - bool hasPagination = specification.PageSize.HasValue || specification.Top.HasValue; - bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; - if (hasPagination && !hasOrdering) - throw new InvalidOperationException("Pagination requires an ordering."); - Func keySelectorFn = selector.Compile(); - IQueryable query = BuildBasicQuery(specification); - query = ApplyOrdering(query, specification); - List items = await query.ToListAsync(cancellationToken); - IEnumerable result = items.GroupBy(keySelectorFn) - .Where(g => g.Count() > Constants.One) - .SelectMany(g => g); - // Pagination applied AFTER grouping so it operates on the duplicate set, not raw rows - if (specification is { Page: not null, PageSize: not null }) - result = result.Skip((specification.Page.Value - Constants.One) * specification.PageSize.Value) - .Take(specification.PageSize.Value); - else if (specification.Top != null) - result = result.Take(specification.Top.Value); - return result; + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateDuplicatesAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + if (specification.Page.HasValue != specification.PageSize.HasValue) + throw new InvalidOperationException("Both Page and PageSize must be set together, or neither."); + if (selector == null) throw new ArgumentNullException(nameof(selector)); + bool hasPagination = specification.PageSize.HasValue || specification.Top.HasValue; + bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; + if (hasPagination && !hasOrdering) + throw new InvalidOperationException("Pagination requires an ordering."); + + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + activity?.SetTag("vali_flow.has_pagination", hasPagination); + activity?.SetTag("vali_flow.has_order_by", hasOrdering); + + Func keySelectorFn = selector.Compile(); + IQueryable query = BuildBasicQuery(specification); + query = ApplyOrdering(query, specification); + List items = await query.ToListAsync(cancellationToken); + IEnumerable result = items.GroupBy(keySelectorFn) + .Where(g => g.Count() > Constants.One) + .SelectMany(g => g); + // Pagination applied AFTER grouping so it operates on the duplicate set, not raw rows + if (specification is { Page: not null, PageSize: not null }) + result = result.Skip((specification.Page.Value - Constants.One) * specification.PageSize.Value) + .Take(specification.PageSize.Value); + else if (specification.Top != null) + result = result.Take(specification.Top.Value); + return result; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -275,16 +385,30 @@ public async Task> EvaluateDuplicatesAsync( ) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - if (specification.Page.HasValue || specification.PageSize.HasValue) - throw new InvalidOperationException( - "EvaluateGetLastFailedAsync does not support pagination. Use EvaluateQueryAsync for paged queries."); - if (specification.OrderBy == null && specification.ValiSort == null) - throw new InvalidOperationException( - $"{nameof(EvaluateGetLastFailedAsync)} requires an ordering (OrderBy or ValiSort). EF Core cannot translate LastOrDefault without ORDER BY."); - - IQueryable query = BuildQuery(specification, negateFilter: true); - return await ExecuteWithExceptionHandlingAsync(() => query.LastOrDefaultAsync(cancellationToken), - nameof(EvaluateGetLastFailedAsync)); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateGetLastFailedAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + if (specification.Page.HasValue || specification.PageSize.HasValue) + throw new InvalidOperationException( + "EvaluateGetLastFailedAsync does not support pagination. Use EvaluateQueryAsync for paged queries."); + if (specification.OrderBy == null && specification.ValiSort == null) + throw new InvalidOperationException( + $"{nameof(EvaluateGetLastFailedAsync)} requires an ordering (OrderBy or ValiSort). EF Core cannot translate LastOrDefault without ORDER BY."); + + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + activity?.SetTag("vali_flow.has_order_by", true); + + IQueryable query = BuildQuery(specification, negateFilter: true); + return await ExecuteWithExceptionHandlingAsync(() => query.LastOrDefaultAsync(cancellationToken), + nameof(EvaluateGetLastFailedAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -302,16 +426,30 @@ public async Task> EvaluateDuplicatesAsync( ) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - if (specification.Page.HasValue || specification.PageSize.HasValue) - throw new InvalidOperationException( - "EvaluateGetLastAsync does not support pagination. Use EvaluateQueryAsync for paged queries."); - if (specification.OrderBy == null && specification.ValiSort == null) - throw new InvalidOperationException( - $"{nameof(EvaluateGetLastAsync)} requires an ordering (OrderBy or ValiSort). EF Core cannot translate LastOrDefault without ORDER BY."); - - IQueryable query = BuildQuery(specification); - return await ExecuteWithExceptionHandlingAsync(() => query.LastOrDefaultAsync(cancellationToken), - nameof(EvaluateGetLastAsync)); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluateGetLastAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + if (specification.Page.HasValue || specification.PageSize.HasValue) + throw new InvalidOperationException( + "EvaluateGetLastAsync does not support pagination. Use EvaluateQueryAsync for paged queries."); + if (specification.OrderBy == null && specification.ValiSort == null) + throw new InvalidOperationException( + $"{nameof(EvaluateGetLastAsync)} requires an ordering (OrderBy or ValiSort). EF Core cannot translate LastOrDefault without ORDER BY."); + + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + activity?.SetTag("vali_flow.has_order_by", true); + + IQueryable query = BuildQuery(specification); + return await ExecuteWithExceptionHandlingAsync(() => query.LastOrDefaultAsync(cancellationToken), + nameof(EvaluateGetLastAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -333,38 +471,68 @@ public async Task> EvaluatePagedAsync( ) { if (specification == null) throw new ArgumentNullException(nameof(specification)); - if (!specification.Page.HasValue) - throw new ArgumentException( - $"{nameof(EvaluatePagedAsync)} requires Page to be explicitly set on the specification.", - nameof(specification)); - if (!specification.PageSize.HasValue) - throw new ArgumentException( - $"{nameof(EvaluatePagedAsync)} requires PageSize to be explicitly set on the specification.", - nameof(specification)); - - bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; - if (!hasOrdering) - throw new InvalidOperationException( - $"{nameof(EvaluatePagedAsync)} requires an ordering (OrderBy or ValiSort) for deterministic pagination results."); - - int page = specification.Page.Value; - int pageSize = specification.PageSize.Value; - - if (page < 1) throw new ArgumentOutOfRangeException(nameof(specification), "Page must be greater than or equal to 1."); - if (pageSize < 1) throw new ArgumentOutOfRangeException(nameof(specification), "PageSize must be greater than or equal to 1."); - - IQueryable baseQuery = BuildBasicQuery(specification); - - int totalCount = await ExecuteWithExceptionHandlingAsync( - () => baseQuery.CountAsync(cancellationToken), - nameof(EvaluatePagedAsync)); - - IQueryable orderedQuery = ApplyOrdering(baseQuery, specification); - int skip = (page - Constants.One) * pageSize; - IList items = await ExecuteWithExceptionHandlingAsync( - () => orderedQuery.Skip(skip).Take(pageSize).ToListAsync(cancellationToken), - nameof(EvaluatePagedAsync)); - - return new PagedResult(items.AsReadOnly(), totalCount, page, pageSize); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.EvaluatePagedAsync", tag: specification.TagWith, entityType: typeof(T).Name); + try + { + if (!specification.Page.HasValue) + throw new ArgumentException( + $"{nameof(EvaluatePagedAsync)} requires Page to be explicitly set on the specification.", + nameof(specification)); + if (!specification.PageSize.HasValue) + throw new ArgumentException( + $"{nameof(EvaluatePagedAsync)} requires PageSize to be explicitly set on the specification.", + nameof(specification)); + + bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; + if (!hasOrdering) + throw new InvalidOperationException( + $"{nameof(EvaluatePagedAsync)} requires an ordering (OrderBy or ValiSort) for deterministic pagination results."); + + int page = specification.Page.Value; + int pageSize = specification.PageSize.Value; + + if (page < 1) throw new ArgumentOutOfRangeException(nameof(specification), "Page must be greater than or equal to 1."); + if (pageSize < 1) throw new ArgumentOutOfRangeException(nameof(specification), "PageSize must be greater than or equal to 1."); + + activity?.SetTag("vali_flow.has_filter", specification.Filter != null); + activity?.SetTag("vali_flow.include_count", specification.Includes?.Count() ?? 0); + activity?.SetTag("vali_flow.has_pagination", true); + activity?.SetTag("vali_flow.has_order_by", hasOrdering); + activity?.SetTag("vali_flow.page", page); + activity?.SetTag("vali_flow.page_size", pageSize); + + IQueryable baseQuery = BuildBasicQuery(specification); + + int totalCount = await ExecuteWithExceptionHandlingAsync( + () => baseQuery.CountAsync(cancellationToken), + nameof(EvaluatePagedAsync)); + + IQueryable orderedQuery = ApplyOrdering(baseQuery, specification); + int skip = (page - Constants.One) * pageSize; + IList items = await ExecuteWithExceptionHandlingAsync( + () => orderedQuery.Skip(skip).Take(pageSize).ToListAsync(cancellationToken), + nameof(EvaluatePagedAsync)); + + return new PagedResult(items.AsReadOnly(), totalCount, page, pageSize); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } + + /// + /// Alias for — provided for API symmetry with + /// Vali-Flow.InMemory's EvaluatePagedResult. See for behavior, + /// requirements, and the count/items round-trip remark. + /// + /// Specification that defines the filter, ordering, pagination, and EF Core query hints. + /// Cancellation token. + /// A with the page items, total count, and pagination metadata. + public Task> EvaluatePagedResultAsync( + IQuerySpecification specification, + CancellationToken cancellationToken = default + ) => EvaluatePagedAsync(specification, cancellationToken); } diff --git a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Write.cs b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Write.cs index d6ac876..7578ce3 100644 --- a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Write.cs +++ b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.Write.cs @@ -1,6 +1,8 @@ +using System.Diagnostics; using System.Linq.Expressions; using EFCore.BulkExtensions; using Microsoft.EntityFrameworkCore; +using Vali_Flow.Abstractions.Diagnostics; using Vali_Flow.Utils; namespace Vali_Flow.Classes.Evaluators; @@ -21,14 +23,25 @@ public async Task AddAsync( CancellationToken cancellationToken = default ) { - Validation.ValidateEntityNotNull(entity); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.AddAsync", tag: null, entityType: typeof(T).Name); + try + { + Validation.ValidateEntityNotNull(entity); + activity?.SetTag("vali_flow.save_changes", saveChanges); - var addedEntity = await ExecuteWithExceptionHandlingAsync( - async () => (await _dbContext.Set().AddAsync(entity, cancellationToken)).Entity, - nameof(AddAsync)); + var addedEntity = await ExecuteWithExceptionHandlingAsync( + async () => (await _dbContext.Set().AddAsync(entity, cancellationToken)).Entity, + nameof(AddAsync)); - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(AddAsync)); - return addedEntity; + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(AddAsync)); + return addedEntity; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -45,21 +58,34 @@ public async Task> AddRangeAsync( CancellationToken cancellationToken = default ) { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - IEnumerable entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.AddRangeAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + IEnumerable entityList = entities.ToList(); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); - await ExecuteWithExceptionHandlingAsync( - async () => - { - await _dbContext.Set().AddRangeAsync(entityList, cancellationToken); - return entityList; - }, nameof(AddRangeAsync)); + activity?.SetTag("vali_flow.save_changes", saveChanges); + activity?.SetTag("vali_flow.entity_count", entityList.Count()); + + await ExecuteWithExceptionHandlingAsync( + async () => + { + await _dbContext.Set().AddRangeAsync(entityList, cancellationToken); + return entityList; + }, nameof(AddRangeAsync)); - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(AddRangeAsync)); - return entityList; + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(AddRangeAsync)); + return entityList; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -76,11 +102,22 @@ public async Task UpdateAsync( CancellationToken cancellationToken = default ) { - Validation.ValidateEntityNotNull(entity); - _dbContext.Set().Update(entity); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.UpdateAsync", tag: null, entityType: typeof(T).Name); + try + { + Validation.ValidateEntityNotNull(entity); + activity?.SetTag("vali_flow.save_changes", saveChanges); + _dbContext.Set().Update(entity); - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpdateAsync)); - return entity; + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpdateAsync)); + return entity; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -97,16 +134,29 @@ public async Task> UpdateRangeAsync( CancellationToken cancellationToken = default ) { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - IEnumerable entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.UpdateRangeAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + IEnumerable entityList = entities.ToList(); + + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + activity?.SetTag("vali_flow.save_changes", saveChanges); + activity?.SetTag("vali_flow.entity_count", entityList.Count()); - _dbContext.Set().UpdateRange(entityList); + _dbContext.Set().UpdateRange(entityList); - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpdateRangeAsync)); - return entityList; + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpdateRangeAsync)); + return entityList; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -122,10 +172,21 @@ public async Task DeleteAsync( CancellationToken cancellationToken = default ) { - Validation.ValidateEntityNotNull(entity); - _dbContext.Set().Remove(entity); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.DeleteAsync", tag: null, entityType: typeof(T).Name); + try + { + Validation.ValidateEntityNotNull(entity); + activity?.SetTag("vali_flow.save_changes", saveChanges); + _dbContext.Set().Remove(entity); - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(DeleteAsync)); + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(DeleteAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -141,15 +202,28 @@ public async Task DeleteRangeAsync( CancellationToken cancellationToken = default ) { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - IEnumerable entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.DeleteRangeAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + IEnumerable entityList = entities.ToList(); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); - _dbContext.Set().RemoveRange(entityList); + activity?.SetTag("vali_flow.save_changes", saveChanges); + activity?.SetTag("vali_flow.entity_count", entityList.Count()); - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(DeleteRangeAsync)); + _dbContext.Set().RemoveRange(entityList); + + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(DeleteRangeAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -159,8 +233,18 @@ public async Task DeleteRangeAsync( /// Cancellation token. public async Task SaveChangesAsync(CancellationToken cancellationToken = default) { - await ExecuteWithExceptionHandlingAsync(() => _dbContext.SaveChangesAsync(cancellationToken), - nameof(SaveChangesAsync)); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.SaveChangesAsync", tag: null, entityType: typeof(T).Name); + try + { + await ExecuteWithExceptionHandlingAsync(() => _dbContext.SaveChangesAsync(cancellationToken), + nameof(SaveChangesAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -180,21 +264,34 @@ public async Task UpsertAsync( CancellationToken cancellationToken = default ) { - Validation.ValidateEntityNotNull(entity); - if (matchCondition == null) throw new ArgumentNullException(nameof(matchCondition)); - T? existingEntity = await _dbContext.Set().FirstOrDefaultAsync(matchCondition, cancellationToken); - - if (existingEntity == null) + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.UpsertAsync", tag: null, entityType: typeof(T).Name); + try { - await _dbContext.Set().AddAsync(entity, cancellationToken); + Validation.ValidateEntityNotNull(entity); + if (matchCondition == null) throw new ArgumentNullException(nameof(matchCondition)); + activity?.SetTag("vali_flow.save_changes", saveChanges); + + T? existingEntity = await _dbContext.Set().FirstOrDefaultAsync(matchCondition, cancellationToken); + activity?.SetTag("vali_flow.upsert_matched_existing", existingEntity != null); + + if (existingEntity == null) + { + await _dbContext.Set().AddAsync(entity, cancellationToken); + } + else + { + _dbContext.Entry(existingEntity).CurrentValues.SetValues(entity); + } + + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpsertAsync)); + return entity; } - else + catch (Exception ex) { - _dbContext.Entry(existingEntity).CurrentValues.SetValues(entity); + ValiFlowDiagnostics.RecordException(activity, ex); + throw; } - - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpsertAsync)); - return entity; } /// @@ -216,56 +313,107 @@ public async Task> UpsertRangeAsync( CancellationToken cancellationToken = default ) where TProperty : notnull { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - if (keySelector == null) throw new ArgumentNullException(nameof(keySelector)); - IEnumerable entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.UpsertRangeAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + if (keySelector == null) throw new ArgumentNullException(nameof(keySelector)); + IEnumerable entityList = entities.ToList(); + + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); + + activity?.SetTag("vali_flow.save_changes", saveChanges); + activity?.SetTag("vali_flow.entity_count", entityList.Count()); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + // Compile keySelector once for in-memory use + var keySelectorFn = keySelector.Compile(); - // Compile keySelector once for in-memory use - var keySelectorFn = keySelector.Compile(); + // Materialize keys as a concrete List — EF can translate .Contains() on a local collection + List keys = entityList.Select(keySelectorFn).ToList(); - // Materialize keys as a concrete List — EF can translate .Contains() on a local collection - List keys = entityList.Select(keySelectorFn).ToList(); + // Build a predicate that EF can translate: e => keys.Contains(e.Prop) + var param = keySelector.Parameters[0]; + var body = Expression.Call( + typeof(Enumerable), + nameof(Enumerable.Contains), + [typeof(TProperty)], + Expression.Constant(keys), + keySelector.Body + ); + var predicate = Expression.Lambda>(body, param); - // Build a predicate that EF can translate: e => keys.Contains(e.Prop) - var param = keySelector.Parameters[0]; - var body = Expression.Call( - typeof(Enumerable), - nameof(Enumerable.Contains), - [typeof(TProperty)], - Expression.Constant(keys), - keySelector.Body - ); - var predicate = Expression.Lambda>(body, param); + IEnumerable existingEntities = await _dbContext.Set() + .Where(predicate) + .ToListAsync(cancellationToken); - IEnumerable existingEntities = await _dbContext.Set() - .Where(predicate) - .ToListAsync(cancellationToken); + Dictionary existingEntityDict = existingEntities.ToDictionary(keySelectorFn, e => e); - Dictionary existingEntityDict = existingEntities.ToDictionary(keySelectorFn, e => e); + Dictionary newEntitiesByKey = + PartitionUpsertRange(entityList, keySelectorFn, existingEntityDict); - var newEntities = new List(); + if (newEntitiesByKey.Count > 0) + await _dbContext.Set().AddRangeAsync(newEntitiesByKey.Values, cancellationToken); + + await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpsertRangeAsync)); + return entityList; + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Splits into entities to insert, applying in-place updates to the ones + /// that already exist in as a side effect. + /// Keyed by (not a List) so duplicate keys within the same incoming + /// batch collapse into a single pending insert instead of each being added separately — last occurrence + /// in the batch wins, matching the "update in place" semantics used for keys that already exist in the database. + /// + private Dictionary PartitionUpsertRange( + IEnumerable entityList, + Func keySelectorFn, + Dictionary existingEntityDict) where TProperty : notnull + { + var newEntitiesByKey = new Dictionary(); foreach (T entity in entityList) { TProperty key = keySelectorFn(entity); if (existingEntityDict.TryGetValue(key, out var existingEntity)) { - _dbContext.Entry(existingEntity).CurrentValues.SetValues(entity); + var entry = _dbContext.Entry(existingEntity); + + // CurrentValues.SetValues(entity) copies every scalar property by name, including the + // primary key. When the caller's incoming entity carries its own (new) Id -- the normal + // case when upserting by a business key like a Sku rather than by the PK -- EF throws + // "The property '...' is part of a key and so cannot be modified" instead of updating in + // place. Align the incoming entity's PK value(s) with the tracked entity's PK first, so + // SetValues sees no change on the key and only applies the real (non-key) updates. + var primaryKey = entry.Metadata.FindPrimaryKey(); + if (primaryKey != null) + { + foreach (var keyProperty in primaryKey.Properties) + { + var propertyInfo = keyProperty.PropertyInfo; + if (propertyInfo == null) continue; + var existingKeyValue = propertyInfo.GetValue(existingEntity); + propertyInfo.SetValue(entity, existingKeyValue); + } + } + + entry.CurrentValues.SetValues(entity); } else { - newEntities.Add(entity); + newEntitiesByKey[key] = entity; } } - if (newEntities.Any()) - await _dbContext.Set().AddRangeAsync(newEntities, cancellationToken); - - await SaveChangesIfRequestedAsync(saveChanges, cancellationToken, nameof(UpsertRangeAsync)); - return entityList; + return newEntitiesByKey; } /// @@ -282,29 +430,43 @@ public async Task DeleteByConditionAsync( ) { if (condition == null) throw new ArgumentNullException(nameof(condition)); - await ExecuteWithExceptionHandlingAsync(async () => - { - bool isInMemory = _dbContext.Database.ProviderName - ?.Contains("InMemory", StringComparison.OrdinalIgnoreCase) == true; + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.DeleteByConditionAsync", tag: null, entityType: typeof(T).Name); + try + { + await ExecuteWithExceptionHandlingAsync( + () => DeleteByConditionCoreAsync(condition, cancellationToken), + nameof(DeleteByConditionAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } - if (!isInMemory) - { - // ExecuteDeleteAsync translates directly to DELETE FROM … WHERE — no round-trip to load entities - await _dbContext.Set().Where(condition).ExecuteDeleteAsync(cancellationToken); - } - else - { - // Fallback for providers that do not support ExecuteDeleteAsync (e.g., InMemory) - var entities = await _dbContext.Set().Where(condition).ToListAsync(cancellationToken); - if (entities.Count > 0) - { - _dbContext.Set().RemoveRange(entities); - await _dbContext.SaveChangesAsync(cancellationToken); - } - } - return 0; - }, - nameof(DeleteByConditionAsync)); + private async Task DeleteByConditionCoreAsync( + Expression> condition, + CancellationToken cancellationToken) + { + bool isInMemory = _dbContext.Database.ProviderName + ?.Contains("InMemory", StringComparison.OrdinalIgnoreCase) == true; + + if (!isInMemory) + { + // ExecuteDeleteAsync translates directly to DELETE FROM … WHERE — no round-trip to load entities + await _dbContext.Set().Where(condition).ExecuteDeleteAsync(cancellationToken); + return 0; + } + + // Fallback for providers that do not support ExecuteDeleteAsync (e.g., InMemory) + var entities = await _dbContext.Set().Where(condition).ToListAsync(cancellationToken); + if (entities.Count > 0) + { + _dbContext.Set().RemoveRange(entities); + await _dbContext.SaveChangesAsync(cancellationToken); + } + return 0; } /// @@ -341,37 +503,78 @@ public async Task ExecuteUpdateAsync( public async Task ExecuteTransactionAsync(Func operations, CancellationToken cancellationToken = default) { if (operations == null) throw new ArgumentNullException(nameof(operations)); - if (_dbContext.Database.CurrentTransaction != null) + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.ExecuteTransactionAsync", tag: null, entityType: typeof(T).Name); + + bool reusedExistingTransaction = _dbContext.Database.CurrentTransaction != null; + activity?.SetTag("vali_flow.reused_existing_transaction", reusedExistingTransaction); + + if (reusedExistingTransaction) { - await operations(); + await RunWithinExistingTransactionAsync(operations, activity); return; } - await using var transaction = await _dbContext.Database.BeginTransactionAsync(cancellationToken); + await RunWithinNewTransactionAsync(operations, activity, cancellationToken); + } + private async Task RunWithinExistingTransactionAsync(Func operations, Activity? activity) + { try { await operations(); - await transaction.CommitAsync(cancellationToken); } catch (Exception ex) { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + private async Task RunWithinNewTransactionAsync( + Func operations, Activity? activity, CancellationToken cancellationToken) + { + try + { + await using var transaction = await _dbContext.Database.BeginTransactionAsync(cancellationToken); + try { - await transaction.RollbackAsync(cancellationToken); + await operations(); + await transaction.CommitAsync(cancellationToken); } - catch (Exception rollbackEx) + catch (Exception ex) { - throw new AggregateException( - $"Transaction failed and rollback also failed in {nameof(ExecuteTransactionAsync)}.", - ex, - rollbackEx); + Exception failure = await RollbackTransactionAsync(transaction, ex, cancellationToken); + throw failure; } + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } - throw new InvalidOperationException( - $"Error executing transaction in {nameof(ExecuteTransactionAsync)}.", - ex); + private async Task RollbackTransactionAsync( + Microsoft.EntityFrameworkCore.Storage.IDbContextTransaction transaction, Exception ex, + CancellationToken cancellationToken) + { + try + { + await transaction.RollbackAsync(cancellationToken); } + catch (Exception rollbackEx) + { + return new AggregateException( + $"Transaction failed and rollback also failed in {nameof(ExecuteTransactionAsync)}.", + ex, + rollbackEx); + } + + return new InvalidOperationException( + $"Error executing transaction in {nameof(ExecuteTransactionAsync)}.", + ex); } /// @@ -388,19 +591,31 @@ public async Task BulkInsertAsync( CancellationToken cancellationToken = default ) { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - var entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.BulkInsertAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + var entityList = entities.ToList(); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); - await ExecuteWithExceptionHandlingAsync( - async () => - { - await _dbContext.BulkInsertAsync(entityList, bulkConfig, cancellationToken: cancellationToken); - return 0; - }, - nameof(BulkInsertAsync)); + activity?.SetTag("vali_flow.entity_count", entityList.Count); + + await ExecuteWithExceptionHandlingAsync( + async () => + { + await _dbContext.BulkInsertAsync(entityList, bulkConfig, cancellationToken: cancellationToken); + return 0; + }, + nameof(BulkInsertAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -417,19 +632,27 @@ public async Task BulkUpdateAsync( CancellationToken cancellationToken = default ) { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - var entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.BulkUpdateAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + var entityList = entities.ToList(); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); - await ExecuteWithExceptionHandlingAsync( - async () => - { - await _dbContext.BulkUpdateAsync(entityList, bulkConfig, cancellationToken: cancellationToken); - return 0; - }, - nameof(BulkUpdateAsync)); + activity?.SetTag("vali_flow.entity_count", entityList.Count); + + await RunGatedBulkUpsertAsync( + () => _dbContext.BulkUpdateAsync(entityList, bulkConfig, cancellationToken: cancellationToken), + nameof(BulkUpdateAsync), cancellationToken, activity); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } /// @@ -446,19 +669,86 @@ public async Task BulkDeleteAsync( CancellationToken cancellationToken = default ) { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - var entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.BulkDeleteAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + var entityList = entities.ToList(); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); - await ExecuteWithExceptionHandlingAsync( - async () => - { - await _dbContext.BulkDeleteAsync(entityList, bulkConfig, cancellationToken: cancellationToken); - return 0; - }, - nameof(BulkDeleteAsync)); + activity?.SetTag("vali_flow.entity_count", entityList.Count); + + await ExecuteWithExceptionHandlingAsync( + async () => + { + await _dbContext.BulkDeleteAsync(entityList, bulkConfig, cancellationToken: cancellationToken); + return 0; + }, + nameof(BulkDeleteAsync)); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } + } + + /// + /// Per-(entity type, UpdateByProperties) in-process gate + generic transient retry for + /// and . Both delegate to + /// EFCore.BulkExtensions, which — for PostgreSQL/MySQL matching by a custom + /// , or for a SQL Server merge deadlock — can fail + /// transiently under real concurrency; see for the full + /// per-engine rationale. + /// + /// + /// Gated per entity type (table), not per key set. + /// A stress run that swept the shared-key pool from 15 up to 10,000 SKUs found the retry activation + /// rate stayed flat across every pool size — ruling out key collision as the cause. The real + /// contention is PostgreSQL's CREATE INDEX CONCURRENTLY (part of the merge EFCore.BulkExtensions + /// runs for a non-PK match), which serializes against *any* other transaction on the *same table*, + /// regardless of which rows/columns either one touches. Gating by key set would let two same-process + /// calls with different UpdateByProperties on the same table run concurrently and still race — + /// gating by type alone is what actually matches the real contention boundary. The retry on top covers + /// what the semaphore cannot: cross-process concurrency (multiple API instances), where the collision + /// still exists at the database level. + /// + private const int BulkUpsertGatePermits = 1; + + private static readonly System.Collections.Concurrent.ConcurrentDictionary BulkUpsertGates = new(); + + private static SemaphoreSlim GetBulkUpsertGate() + { + var key = typeof(T).FullName!; + return BulkUpsertGates.GetOrAdd(key, static _ => new SemaphoreSlim(BulkUpsertGatePermits, BulkUpsertGatePermits)); + } + + private async Task RunGatedBulkUpsertAsync( + Func bulkOperation, string operationName, + CancellationToken cancellationToken, Activity? activity) + { + var gate = GetBulkUpsertGate(); + await gate.WaitAsync(cancellationToken); + try + { + await ExecuteWithExceptionHandlingAsync( + async () => + { + await BulkUpsertRetryPolicy.ExecuteAsync( + bulkOperation, + cancellationToken, + onRetry: (attempt, _) => activity?.SetTag("vali_flow.bulk_upsert_retry_count", attempt)); + return 0; + }, + operationName); + } + finally + { + gate.Release(); + } } /// @@ -475,18 +765,26 @@ public async Task BulkInsertOrUpdateAsync( CancellationToken cancellationToken = default ) { - if (entities == null) throw new ArgumentNullException(nameof(entities)); - var entityList = entities.ToList(); + using var activity = ValiFlowDiagnostics.StartActivity( + "Vali-Flow.BulkInsertOrUpdateAsync", tag: null, entityType: typeof(T).Name); + try + { + if (entities == null) throw new ArgumentNullException(nameof(entities)); + var entityList = entities.ToList(); - Validation.ValidateEntitiesNotNull(entityList); - Validation.ValidateEntitiesEmpty(entityList); + Validation.ValidateEntitiesNotNull(entityList); + Validation.ValidateEntitiesEmpty(entityList); - await ExecuteWithExceptionHandlingAsync( - async () => - { - await _dbContext.BulkInsertOrUpdateAsync(entityList, bulkConfig, cancellationToken: cancellationToken); - return 0; - }, - nameof(BulkInsertOrUpdateAsync)); + activity?.SetTag("vali_flow.entity_count", entityList.Count); + + await RunGatedBulkUpsertAsync( + () => _dbContext.BulkInsertOrUpdateAsync(entityList, bulkConfig, cancellationToken: cancellationToken), + nameof(BulkInsertOrUpdateAsync), cancellationToken, activity); + } + catch (Exception ex) + { + ValiFlowDiagnostics.RecordException(activity, ex); + throw; + } } } diff --git a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.cs b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.cs index cdd7001..07e35aa 100644 --- a/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.cs +++ b/Vali-Flow/Classes/Evaluators/ValiFlowEvaluator.cs @@ -6,9 +6,7 @@ using Vali_Flow.Core.Builder; using Vali_Flow.Interfaces.Evaluators.Read; using Vali_Flow.Interfaces.Evaluators.Write; -using Vali_Flow.Interfaces.Options; using Vali_Flow.Interfaces.Specification; -using Vali_Flow.Utils; namespace Vali_Flow.Classes.Evaluators; @@ -20,6 +18,7 @@ namespace Vali_Flow.Classes.Evaluators; public partial class ValiFlowEvaluator : IEvaluatorRead, IEvaluatorWrite where T : class { private readonly DbContext _dbContext; + private readonly QuerySpecificationBuilder _queryBuilder; /// /// Initializes a new instance of the class. @@ -29,57 +28,21 @@ public partial class ValiFlowEvaluator : IEvaluatorRead, IEvaluatorWrite(_dbContext); } #region Methods Private - private IQueryable ApplyAsNoTracking(IQueryable query, bool asNoTracking = true) => asNoTracking ? query.AsNoTracking() : query; - - private IQueryable ApplyAsNoTrackingWithIdentityResolution(IQueryable query, bool apply) - => apply ? query.AsNoTrackingWithIdentityResolution() : query; - - private IQueryable ApplyTagWith(IQueryable query, string? tag) - => tag != null ? query.TagWith(tag) : query; - - private IQueryable ApplyIgnoreAutoIncludes(IQueryable query, bool apply) - => apply ? query.IgnoreAutoIncludes() : query; - - private IQueryable ApplyIncludes(IQueryable query, IEnumerable>? includes) - { - if (includes != null) - { - foreach (var include in includes) - { - query = include.ApplyInclude(query); - } - } + // Query construction (filter, includes, tracking, ordering, pagination) lives in QuerySpecificationBuilder — + // these are thin delegating wrappers kept so Read/Write/Aggregates/Grouped partial files don't need to change. + private IQueryable BuildBasicQuery(ISpecification specification, bool negateCondition = false) + => _queryBuilder.BuildBasicQuery(specification, negateCondition); - return query; - } + private IQueryable BuildQuery(IQuerySpecification specification, bool negateFilter = false) + => _queryBuilder.BuildQuery(specification, negateFilter); private IQueryable ApplyOrdering(IQueryable query, IQuerySpecification specification) - { - if (specification.ValiSort != null) - return specification.ValiSort.Apply(query); - - if (specification.OrderBy == null) - { - if (specification.ThenBys != null) - throw new InvalidOperationException( - "ThenBy requires a primary OrderBy. Set OrderBy on the specification before adding ThenBy expressions."); - return query; - } - - IOrderedQueryable orderedQuery = specification.OrderBy.ApplyOrderBy(query); - - if (specification.ThenBys != null) - { - foreach (var thenBy in specification.ThenBys) - orderedQuery = thenBy.ApplyThenBy(orderedQuery); - } - - return orderedQuery; - } + => _queryBuilder.ApplyOrdering(query, specification); private async Task ExecuteWithExceptionHandlingAsync(Func> operation, string operationName) @@ -95,78 +58,6 @@ private async Task ExecuteWithExceptionHandlingAsync(Func ApplyPagination(IQueryable query, IQuerySpecification specification) - { - if (specification is { Page: not null, PageSize: not null }) - { - int skip = (specification.Page.Value - Constants.One) * specification.PageSize.Value; - int take = specification.PageSize.Value; - query = query.Skip(skip).Take(take); - } - else if (specification.Top != null) - { - query = query.Take(specification.Top.Value); - } - - return query; - } - - private IQueryable ApplyAsSplitQuery(IQueryable query, bool asSplitQuery = false) => asSplitQuery ? query.AsSplitQuery() : query; - - private IQueryable BuildBasicQuery(ISpecification specification, bool negateCondition = false) - { - IQueryable query = _dbContext.Set(); - - query = ApplyIgnoreQueryFilters(query, specification.IgnoreQueryFilters); - query = ApplyIgnoreAutoIncludes(query, specification.IgnoreAutoIncludes); - query = ApplyWhere(query, specification.Filter, negateCondition); - - if (specification.AsNoTracking && specification.AsNoTrackingWithIdentityResolution) - throw new InvalidOperationException( - "AsNoTracking and AsNoTrackingWithIdentityResolution are mutually exclusive. " + - "Use WithAsNoTracking(false) before calling WithAsNoTrackingWithIdentityResolution(true)."); - - query = ApplyAsNoTracking(query, specification.AsNoTracking); - query = ApplyAsNoTrackingWithIdentityResolution(query, specification.AsNoTrackingWithIdentityResolution); - query = ApplyIncludes(query, specification.Includes); - query = ApplyAsSplitQuery(query, specification.AsSplitQuery); - query = ApplyTagWith(query, specification.TagWith); - - return query; - } - - private IQueryable ApplyWhere(IQueryable query, ValiFlowQuery filter, bool negateCondition = false) - { - Validation.ValidateFilterNotNull(filter); - - Expression> condition = negateCondition ? filter.BuildNegated() : filter.BuildWithGlobal(); - return query.Where(condition); - } - - private IQueryable BuildQuery(IQuerySpecification specification, bool negateFilter = false) - { - if (specification.Top.HasValue && (specification.Page.HasValue || specification.PageSize.HasValue)) - throw new InvalidOperationException( - "Cannot combine Top with Page/PageSize pagination on the same specification. Use one or the other."); - - if ((specification.Page.HasValue && specification.Page.Value > 0 && (!specification.PageSize.HasValue || specification.PageSize.Value <= 0)) || - (specification.PageSize.HasValue && specification.PageSize.Value > 0 && (!specification.Page.HasValue || specification.Page.Value <= 0))) - throw new InvalidOperationException( - "Both Page and PageSize must be set together. Use WithPagination(page, pageSize)."); - - bool hasPagination = specification.Page.HasValue || specification.PageSize.HasValue; - bool hasOrdering = specification.OrderBy != null || specification.ValiSort != null; - if (hasPagination && !hasOrdering) - throw new InvalidOperationException( - "Pagination requires an ordering to produce deterministic results. " + - "Set OrderBy or ValiSort on the specification before enabling pagination."); - - IQueryable query = BuildBasicQuery(specification, negateFilter); - query = ApplyOrdering(query, specification); - query = ApplyPagination(query, specification); - return query; - } - private async Task SaveChangesIfRequestedAsync(bool saveChanges, CancellationToken cancellationToken, string operationName) { @@ -178,9 +69,6 @@ await ExecuteWithExceptionHandlingAsync( } } - private IQueryable ApplyIgnoreQueryFilters(IQueryable query, bool ignoreQueryFilters = false) => - ignoreQueryFilters ? query.IgnoreQueryFilters() : query; - private sealed class ParameterReplacerVisitor : ExpressionVisitor { private readonly ParameterExpression _oldParameter; diff --git a/Vali-Flow/Classes/Repository/GenericRepository.cs b/Vali-Flow/Classes/Repository/GenericRepository.cs new file mode 100644 index 0000000..46b9299 --- /dev/null +++ b/Vali-Flow/Classes/Repository/GenericRepository.cs @@ -0,0 +1,83 @@ +using System.Linq.Expressions; +using Microsoft.EntityFrameworkCore; +using Vali_Flow.Classes.Evaluators; +using Vali_Flow.Classes.Specification; +using Vali_Flow.Core.Builder; +using Vali_Flow.Interfaces.Repository; +using Vali_Flow.Models; + +namespace Vali_Flow.Classes.Repository; + +/// +/// Convenience repository that wraps a . It does not reimplement any +/// query/persistence logic — every member is a thin delegation to the evaluator's existing read/write surface. +/// +/// The entity type. Must be a reference type. +/// The type of the entity's primary key. +public sealed class GenericRepository : IGenericRepository where T : class where TKey : IEquatable +{ + private readonly ValiFlowEvaluator _evaluator; + private readonly Expression> _idSelector; + + /// + /// Initializes a new instance of . + /// + /// The underlying evaluator this repository delegates to. + /// + /// Expression identifying the entity's primary key (e.g. x => x.Id). + /// has no built-in concept of a primary key — it only works with specifications/filters — so the repository + /// needs this to build an EqualTo filter for . + /// + public GenericRepository(ValiFlowEvaluator evaluator, Expression> idSelector) + { + _evaluator = evaluator ?? throw new ArgumentNullException(nameof(evaluator)); + _idSelector = idSelector ?? throw new ArgumentNullException(nameof(idSelector)); + } + + /// + public Task GetByIdAsync(TKey id, CancellationToken cancellationToken = default) + { + ValiFlowQuery filter = new ValiFlowQuery().EqualTo(_idSelector, id); + BasicSpecification spec = new(filter); + return _evaluator.EvaluateGetFirstAsync(spec, cancellationToken); + } + + /// + public async Task> GetAllAsync(ValiFlowQuery? filter = null, CancellationToken cancellationToken = default) + { + QuerySpecification spec = filter is null ? new QuerySpecification() : new QuerySpecification(filter); + IQueryable query = await _evaluator.EvaluateQueryAsync(spec); + return await query.ToListAsync(cancellationToken); + } + + /// + public Task> GetPagedAsync( + ValiFlowQuery? filter, + Expression> orderBy, + int page, + int pageSize, + bool ascending = true, + CancellationToken cancellationToken = default + ) where TOrderKey : notnull + { + QuerySpecification spec = filter is null ? new QuerySpecification() : new QuerySpecification(filter); + spec.WithOrderBy(orderBy, ascending).WithPagination(page, pageSize); + return _evaluator.EvaluatePagedResultAsync(spec, cancellationToken); + } + + /// + public Task AddAsync(T entity, bool saveChanges = true, CancellationToken cancellationToken = default) + => _evaluator.AddAsync(entity, saveChanges, cancellationToken); + + /// + public Task UpdateAsync(T entity, bool saveChanges = true, CancellationToken cancellationToken = default) + => _evaluator.UpdateAsync(entity, saveChanges, cancellationToken); + + /// + public Task DeleteAsync(T entity, bool saveChanges = true, CancellationToken cancellationToken = default) + => _evaluator.DeleteAsync(entity, saveChanges, cancellationToken); + + /// + public Task SaveChangesAsync(CancellationToken cancellationToken = default) + => _evaluator.SaveChangesAsync(cancellationToken); +} diff --git a/Vali-Flow/Interfaces/Evaluators/Read/IEvaluatorRead.cs b/Vali-Flow/Interfaces/Evaluators/Read/IEvaluatorRead.cs index 9da3ae5..a15360a 100644 --- a/Vali-Flow/Interfaces/Evaluators/Read/IEvaluatorRead.cs +++ b/Vali-Flow/Interfaces/Evaluators/Read/IEvaluatorRead.cs @@ -152,7 +152,7 @@ Task> EvaluateDuplicatesAsync( /// The specification defining the filtering and inclusion criteria. /// The expression to select the property to evaluate. /// A token to cancel the asynchronous operation. - /// A task that represents the asynchronous operation, returning the minimum value of the selected property. + /// A task that represents the asynchronous operation, returning the minimum value of the selected property, or default(TResult) if no entity matches the specification. Task EvaluateMinAsync( IBasicSpecification specification, Expression> selector, @@ -166,7 +166,7 @@ Task EvaluateMinAsync( /// The specification defining the filtering and inclusion criteria. /// The expression to select the property to evaluate. /// A token to cancel the asynchronous operation. - /// A task that represents the asynchronous operation, returning the maximum value of the selected property. + /// A task that represents the asynchronous operation, returning the maximum value of the selected property, or default(TResult) if no entity matches the specification. Task EvaluateMaxAsync( IBasicSpecification specification, Expression> selector, @@ -658,6 +658,18 @@ Task> EvaluatePagedAsync( CancellationToken cancellationToken = default ); + /// + /// Alias for — provided for API symmetry with + /// Vali-Flow.InMemory's EvaluatePagedResult. + /// + /// The specification defining the filtering, ordering, and pagination criteria. + /// A token to cancel the asynchronous operation. + /// A task that represents the asynchronous operation, returning a with the items and pagination metadata. + Task> EvaluatePagedResultAsync( + IQuerySpecification specification, + CancellationToken cancellationToken = default + ); + /// /// Asynchronously retrieves the top entities satisfying the specification. /// diff --git a/Vali-Flow/Interfaces/Repository/IGenericRepository.cs b/Vali-Flow/Interfaces/Repository/IGenericRepository.cs new file mode 100644 index 0000000..813c93b --- /dev/null +++ b/Vali-Flow/Interfaces/Repository/IGenericRepository.cs @@ -0,0 +1,50 @@ +using System.Linq.Expressions; +using Vali_Flow.Core.Builder; +using Vali_Flow.Models; + +namespace Vali_Flow.Interfaces.Repository; + +/// +/// High-level, mockable convenience wrapper over . +/// Every member delegates to the underlying evaluator — it does not reimplement any query or persistence logic. +/// +/// The entity type. Must be a reference type. +/// The type of the entity's primary key. +public interface IGenericRepository where T : class where TKey : IEquatable +{ + /// + /// Retrieves the entity whose key (as defined by the idSelector passed to the repository constructor) + /// equals , or null if none matches. + /// + Task GetByIdAsync(TKey id, CancellationToken cancellationToken = default); + + /// + /// Retrieves all entities matching (or every entity when is null). + /// + Task> GetAllAsync(ValiFlowQuery? filter = null, CancellationToken cancellationToken = default); + + /// + /// Retrieves a page of entities matching , ordered by . + /// Ordering is required because deterministic pagination needs an ORDER BY. + /// + Task> GetPagedAsync( + ValiFlowQuery? filter, + Expression> orderBy, + int page, + int pageSize, + bool ascending = true, + CancellationToken cancellationToken = default + ) where TOrderKey : notnull; + + /// Adds a single entity. See . + Task AddAsync(T entity, bool saveChanges = true, CancellationToken cancellationToken = default); + + /// Updates a single entity. See . + Task UpdateAsync(T entity, bool saveChanges = true, CancellationToken cancellationToken = default); + + /// Deletes a single entity. See . + Task DeleteAsync(T entity, bool saveChanges = true, CancellationToken cancellationToken = default); + + /// Persists any pending changes tracked by the underlying . + Task SaveChangesAsync(CancellationToken cancellationToken = default); +} diff --git a/Vali-Flow/Vali-Flow.csproj b/Vali-Flow/Vali-Flow.csproj index 4beb2a7..bfc706a 100644 --- a/Vali-Flow/Vali-Flow.csproj +++ b/Vali-Flow/Vali-Flow.csproj @@ -14,7 +14,7 @@ Vali-Flow Vali-Flow Vali-Flow - 1.3.4 + 1.4.0 Felipe Rafael Montenegro Morriberon Copyright © 2026 - FM. All rights reserved. @@ -40,7 +40,9 @@ snupkg Vali-Flow is a .NET library that simplifies data access in Entity Framework Core applications via a fluent specification API. Provides ValiFlowEvaluator for querying and writing data, QuerySpecification and BasicSpecification for defining query criteria, and bulk operation support via EFCore.BulkExtensions. - v1.3.4 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. + v1.4.0 — Add GenericRepository<T,TKey> (GetById/GetAll/GetPaged/Add/Update/Delete/SaveChanges, wraps ValiFlowEvaluator<T>). Instrument read/write evaluator methods with ValiFlowDiagnostics Activity tracing. Fix UpsertRangeAsync duplicate-key bug and a PK-overwrite bug in upsert-by-business-key scenarios. Serialize concurrent BulkInsertOrUpdateAsync/BulkUpdateAsync calls per entity type with a generic transient-failure retry (SQL Server/PostgreSQL/MySQL/SQLite). No breaking changes. + +v1.3.4 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. v1.3.3 — Updated Vali-Flow.Core dependency to 2.0.1. @@ -53,7 +55,7 @@ v1.3.0 — Made ValiFlowEvaluator<T> inheritable (removed sealed modifier) - + diff --git a/docs/en/architecture/overview.md b/docs/en/architecture/overview.md index 8ed77d5..9919eda 100644 --- a/docs/en/architecture/overview.md +++ b/docs/en/architecture/overview.md @@ -10,7 +10,8 @@ │ IR nodes: EqualNode, ComparisonNode, LikeNode, │ │ InNode, NullNode, AndNode, OrNode, NotNode │ └────────────────────────┬────────────────────────────────┘ - │ ProjectReference (all packages) + │ PackageReference (NuGet — see CLAUDE.md for the + │ current repo-state caveat on internal cross-refs) ┌──────────────┼──────────────────┐ │ │ │ ▼ ▼ ▼ @@ -76,6 +77,11 @@ Each adapter has a single responsibility: convert IR nodes to the query format e | `Vali-Flow.NoSql.Elasticsearch` | `Query` | `Elastic.Clients.Elasticsearch` | | `Vali-Flow.NoSql.DynamoDB` | `DynamoFilterExpression` | `AWSSDK.DynamoDBv2` | | `Vali-Flow.NoSql.Redis` | `string` (RediSearch DSL) | `NRedisStack` | +| `Vali-Flow.NoSql.Couchbase` | `CouchbaseFilterExpression` (N1QL text + params) | none — text output, no SDK needed | +| `Vali-Flow.NoSql.CosmosDb` | `CosmosFilterExpression` (SQL API text + params) | none — text output, no SDK needed | +| `Vali-Flow.NoSql.Firestore` | `Filter` (native) | `Google.Cloud.Firestore` | + +> Mongo/Elasticsearch/DynamoDB/Firestore return a **native SDK object** because their query language *is* an object graph. Sql/Couchbase/CosmosDb return **parameterized text** because their query language *is* text — the consumer applies it with their own client. See "Translator design pattern" in the root `CLAUDE.md` before adding a new provider. --- @@ -134,16 +140,25 @@ Vali-Flow.sln ├── Vali-Flow.NoSql.DynamoDB/ DynamoDB adapter ├── Vali-Flow.NoSql.Elasticsearch/ Elasticsearch adapter ├── Vali-Flow.NoSql.Redis/ Redis/RediSearch adapter +├── Vali-Flow.NoSql.Couchbase/ Couchbase (N1QL) adapter +├── Vali-Flow.NoSql.CosmosDb/ Azure Cosmos DB (SQL API) adapter +├── Vali-Flow.NoSql.Firestore/ Google Cloud Firestore adapter ├── Vali-Flow.Abstractions/ Shared interfaces -├── Vali-Flow.Benchmarks/ BenchmarkDotNet benchmarks +├── Vali-Flow.Benchmarks/ BenchmarkDotNet benchmarks (InMemory, Sql, EF Core) ├── Vali-Flow.Tests/ EF Core evaluator tests ├── Vali-Flow.InMemory.Tests/ InMemory evaluator tests ├── Vali-Flow.Sql.Tests/ SQL translator tests -├── Vali-Flow.NoSql.Tests/ NoSQL base tests -└── Vali-Flow.NoSql.DynamoDB.Tests/ DynamoDB tests +├── Vali-Flow.NoSql.Tests/ NoSQL base + MongoDB tests +├── Vali-Flow.NoSql.DynamoDB.Tests/ +├── Vali-Flow.NoSql.Elasticsearch.Tests/ +├── Vali-Flow.NoSql.Redis.Tests/ +├── Vali-Flow.NoSql.Couchbase.Tests/ +├── Vali-Flow.NoSql.CosmosDb.Tests/ +├── Vali-Flow.NoSql.Firestore.Tests/ +└── Vali-Flow.Abstractions.Tests/ ``` -All packages target `net8.0` and `net9.0`. +All packages target `net8.0` and `net9.0`, and also run unmodified on **.NET 10** thanks to .NET's forward compatibility. --- diff --git a/docs/en/guides/getting-started.md b/docs/en/guides/getting-started.md index d36bacc..4a4b372 100644 --- a/docs/en/guides/getting-started.md +++ b/docs/en/guides/getting-started.md @@ -4,7 +4,7 @@ This guide walks you through installing and using the Vali-Flow ecosystem from s ## Prerequisites -- .NET 8 or .NET 9 +- .NET 8 or .NET 9 (also runs on .NET 10 via forward compatibility) - A C# project (any type: web API, console, test project, etc.) --- diff --git a/docs/en/internal/benchmarks.md b/docs/en/internal/benchmarks.md index 92d0cff..958af16 100644 --- a/docs/en/internal/benchmarks.md +++ b/docs/en/internal/benchmarks.md @@ -1,6 +1,6 @@ # Vali-Flow Benchmarks -The `Vali-Flow.Benchmarks` project measures the performance of the InMemory evaluator and the SQL builder using [BenchmarkDotNet](https://benchmarkdotnet.org/). +The `Vali-Flow.Benchmarks` project measures the performance of the InMemory evaluator, the SQL builder, and the EF Core evaluator using [BenchmarkDotNet](https://benchmarkdotnet.org/). --- @@ -20,6 +20,7 @@ To run a specific benchmark class: ```bash dotnet run --configuration Release -- --filter "*InMemoryFilter*" dotnet run --configuration Release -- --filter "*SqlBuilder*" +dotnet run --configuration Release -- --filter "*EfCore*" ``` --- @@ -45,6 +46,14 @@ All InMemory benchmarks parameterize over `N ∈ { 1 000, 10 000, 100 000 }` to |-------|-----------------| | `SqlBuilderBenchmarks` | `SqlQueryBuilder` SELECT with JOINs, INSERT, UPDATE — construction cost only (no DB round-trip) | +### EF Core evaluator + +Uses the EF Core **InMemory provider** (`Microsoft.EntityFrameworkCore.InMemory`) — this measures the overhead of `ValiFlowEvaluator` / `QuerySpecificationBuilder` (query construction + LINQ translation), not real database I/O. Parameterized over `N ∈ { 1 000, 10 000, 100 000 }`. + +| Class | What it measures | +|-------|-----------------| +| `EfCoreBenchmarks` | `EvaluateQueryAsync` filter (baseline: raw LINQ `.Where()` on the same `DbContext`), `EvaluatePagedAsync`, `EvaluateCountAsync` | + --- ## Interpreting results @@ -76,8 +85,8 @@ BenchmarkDotNet reports: ## Known limitations -- **No NoSQL benchmarks** — `Vali-Flow.NoSql.*` translators are not benchmarked. Translation is CPU-only (no I/O) and the trees are small, so overhead is expected to be sub-microsecond. -- **No EF Core benchmarks** — EF Core performance is dominated by the database round-trip, not the Vali-Flow layer. Profiling should be done with actual query plans, not microbenchmarks. +- **No NoSQL benchmarks** — `Vali-Flow.NoSql.*` translators (7 providers) are not benchmarked. Translation is CPU-only (no I/O) and the trees are small, so overhead is expected to be sub-microsecond. +- **EF Core benchmarks measure construction, not real I/O** — `EfCoreBenchmarks` uses the InMemory EF Core provider, so it isolates `ValiFlowEvaluator`/`QuerySpecificationBuilder` overhead. Real database performance is dominated by the round-trip and query plan, not this layer — profile actual query plans against a real provider for that. --- diff --git a/docs/en/vali-flow-ef-core.md b/docs/en/vali-flow-ef-core.md index ecc2bf9..9936eef 100644 --- a/docs/en/vali-flow-ef-core.md +++ b/docs/en/vali-flow-ef-core.md @@ -78,7 +78,7 @@ dotnet add package Vali-Flow **Requirements** -- .NET 8 or later +- .NET 8, 9, or 10 (built for net8.0/net9.0, runs unmodified on .NET 10 via forward compatibility) - Entity Framework Core 8 or later --- diff --git a/docs/en/vali-flow-nosql-cosmosdb.md b/docs/en/vali-flow-nosql-cosmosdb.md new file mode 100644 index 0000000..5c006de --- /dev/null +++ b/docs/en/vali-flow-nosql-cosmosdb.md @@ -0,0 +1,261 @@ +# Vali-Flow.NoSql.CosmosDb — Complete Reference + +## Table of Contents + +1. [Overview](#overview) +2. [Installation](#installation) +3. [Quick Start](#quick-start) +4. [Extension Methods](#extension-methods) +5. [CosmosFilterExpression](#cosmosfilterexpression) +6. [Supported Operations](#supported-operations) +7. [Type Mapping](#type-mapping) +8. [Custom Value Converter](#custom-value-converter) +9. [Limitations](#limitations) +10. [Full Example](#full-example) + +--- + +## Overview + +**Vali-Flow.NoSql.CosmosDb** translates a `ValiFlow` expression tree into an Azure Cosmos DB SQL API WHERE clause fragment (a `string`) together with the parameter dictionary required to bind it to a `QueryDefinition`. + +The package depends only on `Vali-Flow.NoSql` (the IR layer). Unlike the Mongo/Elasticsearch/DynamoDB translators, it has **no dependency on the `Microsoft.Azure.Cosmos` SDK** — it is a pure string/parameter builder with no connection or execution concerns. You wire the result into your own `QueryDefinition`. + +--- + +## Installation + +```bash +dotnet add package Vali-Flow.NoSql.CosmosDb +``` + +`Vali-Flow.Core` is included as a transitive dependency. The `Microsoft.Azure.Cosmos` SDK is **not** a dependency — add it yourself to actually execute the query. + +--- + +## Quick Start + +```csharp +using Microsoft.Azure.Cosmos; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.CosmosDb.Extensions; +using Vali_Flow.NoSql.CosmosDb.Models; + +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Active") + .GreaterThan(x => x.Total, 100m); + +CosmosFilterExpression f = filter.ToCosmosDb(); + +var queryText = $"SELECT * FROM c WHERE {f.WhereClause}"; +var query = new QueryDefinition(queryText); +foreach (var kv in f.Parameters) + query = query.WithParameter(kv.Key, kv.Value); + +using FeedIterator iterator = container.GetItemQueryIterator(query); +while (iterator.HasMoreResults) +{ + FeedResponse response = await iterator.ReadNextAsync(); + foreach (Order order in response) { /* ... */ } +} +``` + +--- + +## Extension Methods + +Both overloads are in `Vali_Flow.NoSql.CosmosDb.Extensions.ValiFlowCosmosDbExtensions`. + +### `ToCosmosDb(this ValiFlow flow, Func? customConverter = null)` + +Translates the conditions accumulated in a `ValiFlow` builder into a `CosmosFilterExpression`. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `flow` | `ValiFlow` | Yes | The builder containing the conditions. | +| `customConverter` | `Func?` | No | Hook for mapping CLR types not handled by the built-in switch into the raw value stored in the parameters dictionary. Return `null` to fall through to the default conversion. | + +**Returns:** `CosmosFilterExpression` — append `WhereClause` to your query text and bind `Parameters` to a `QueryDefinition`. + +### `ToCosmosDb(this Expression> expression, Func? customConverter = null)` + +Same translation for a pre-built `Expression>`. + +```csharp +Expression> expr = u => u.IsActive && u.Age >= 21; +CosmosFilterExpression f = expr.ToCosmosDb(); +``` + +--- + +## CosmosFilterExpression + +`CosmosFilterExpression` is a sealed class that encapsulates the two values a Cosmos SQL query needs: + +| Property | Type | Description | +|----------|------|-------------| +| `WhereClause` | `string` | The WHERE clause fragment, **without** the leading `WHERE` keyword, e.g. `"c.Age > @p0"`. | +| `Parameters` | `IReadOnlyDictionary` | Maps placeholders (`@p0`, `@p1`, …) to their raw values. | + +Field references use the standard Cosmos SQL container alias `c` (e.g. `c.Status`), so there is no attribute-name placeholder layer like DynamoDB's `#f0` — only value placeholders are generated. + +`Parameters` is used directly with `QueryDefinition.WithParameter(name, value)` in a `foreach` loop — no `.ToDictionary()` call is required, since the SDK's `WithParameter` takes one key/value pair at a time rather than a dictionary constructor argument. + +--- + +## Supported Operations + +| ValiFlow method | IR node | Cosmos SQL fragment | +|----------------|---------|---------------------| +| `.EqualTo(x => x.Field, v)` | `EqualNode(IsNegated: false)` | `c.Field = @p0` | +| `.NotEqualTo(x => x.Field, v)` | `EqualNode(IsNegated: true)` | `c.Field != @p0` | +| `.GreaterThan(x => x.Field, v)` | `ComparisonNode(GT)` | `c.Field > @p0` | +| `.GreaterThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(GTE)` | `c.Field >= @p0` | +| `.LessThan(x => x.Field, v)` | `ComparisonNode(LT)` | `c.Field < @p0` | +| `.LessThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(LTE)` | `c.Field <= @p0` | +| `.Contains(x => x.Field, "txt")` | `LikeNode(Contains)` | `CONTAINS(c.Field, @p0)` | +| `.StartsWith(x => x.Field, "pre")` | `LikeNode(StartsWith)` | `STARTSWITH(c.Field, @p0)` | +| `.EndsWith(x => x.Field, "suf")` | `LikeNode(EndsWith)` | `ENDSWITH(c.Field, @p0)` | +| `.In(x => x.Field, list)` | `InNode` | `c.Field IN (@p0, @p1, …)` | +| `.IsNull(x => x.Field)` | `NullNode(IsNull)` | `IS_NULL(c.Field)` | +| `.IsNotNull(x => x.Field)` | `NullNode(IsNotNull)` | `NOT IS_NULL(c.Field)` | +| `.And(a, b)` | `AndNode` | `(a AND b)` | +| `.Or(a, b)` | `OrNode` | `(a OR b)` | +| `.Not(inner)` | `NotNode` | `NOT (inner)` | + +All three `LikeNode` operators map to **native** Cosmos SQL functions — unlike DynamoDB, Cosmos supports `ENDSWITH` directly, so there is no client-side fallback needed for that case. `IS_NULL` is also native — it is a true null check against the JSON document, not an attribute-existence check. + +--- + +## Type Mapping + +The built-in conversion switch handles these CLR types: + +| CLR type | Parameter value produced | +|----------|---------------------------| +| `null` | `null` | +| `bool` | `b` (as-is) | +| `string` | `s` (as-is) | +| `int` | `i` (as-is) | +| `long` | `l` (as-is) | +| `double` | `d` (as-is) | +| `float` | `f` (as-is) | +| `decimal` | `m` (as-is) | +| `Guid` | `g.ToString()` | +| `Enum` | underlying value as `long` (InvariantCulture) | +| anything else | `v.ToString()` | + +Unlike DynamoDB's `AttributeValue` wrapper, Cosmos parameters are plain CLR values — `QueryDefinition.WithParameter` accepts them directly and the Cosmos SQL API handles JSON-native typing (numbers, strings, booleans) on its own. + +--- + +## Custom Value Converter + +Use `customConverter` when your domain types are not in the table above or when you need a different raw value than the default. + +The converter is called **before** the built-in switch. Return `null` to let the default handle the value. + +```csharp +// Domain type +record Money(decimal Amount, string Currency); + +// Converter: store Money as a number (amount only) +CosmosFilterExpression f = new ValiFlow() + .GreaterThan(x => x.Total, new Money(500m, "USD")) + .ToCosmosDb(value => + { + if (value is Money m) + return m.Amount; + return null; + }); +``` + +Storing a `DateTimeOffset` as an ISO-8601 string: + +```csharp +CosmosFilterExpression f = new ValiFlow() + .GreaterThan(x => x.StartsAt, DateTimeOffset.UtcNow) + .ToCosmosDb(value => + { + if (value is DateTimeOffset dto) + return dto.ToString("O"); + return null; + }); +``` + +--- + +## Limitations + +| Limitation | Detail | +|-----------|--------| +| No Cosmos SDK dependency | This package only produces `WhereClause` + `Parameters`. It does not build or run a `QueryDefinition`, open a `Container`, or page through a `FeedIterator` — that is entirely up to the consumer, unlike the Mongo/Elasticsearch/DynamoDB translators which target their SDK's native request/filter types more directly. | +| Empty `In` list | Throws `InvalidOperationException`. Cosmos DB SQL does not accept an empty `IN (...)` list. Filter the empty case before building the query. | +| No enforced `In` size limit | This package does not cap the number of values in an `In` list (unlike DynamoDB's 100-value SDK limit). Very large lists still count against Cosmos DB's own query text length and complexity limits — keep lists reasonably small. | +| One placeholder per `In` value | `IN (@p0, @p1, @p2, …)` — Cosmos SQL does not accept a single array parameter for `IN`, so each value gets its own placeholder, same as the filter's other parameters. | + +--- + +## Full Example + +A realistic filter combining equality, range, membership, and null checks, applied through the `Microsoft.Azure.Cosmos` SDK: + +```csharp +using Microsoft.Azure.Cosmos; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.CosmosDb.Extensions; +using Vali_Flow.NoSql.CosmosDb.Models; + +CosmosClient client = new CosmosClient(connectionString); +Container container = client.GetContainer("myDb", "Orders"); + +// Build the filter +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Processing") + .GreaterThanOrEqualTo(x => x.Total, 100m) + .LessThan(x => x.Total, 5000m) + .In(x => x.RegionCode, new[] { "US", "CA", "MX" }) + .IsNotNull(x => x.CustomerId); + +CosmosFilterExpression f = filter.ToCosmosDb(); + +// f.WhereClause: +// "(((c.Status = @p0 AND c.Total >= @p1) AND c.Total < @p2) AND c.RegionCode IN (@p3, @p4, @p5)) AND NOT IS_NULL(c.CustomerId)" + +var queryText = $"SELECT * FROM c WHERE {f.WhereClause}"; +var query = new QueryDefinition(queryText); +foreach (var kv in f.Parameters) + query = query.WithParameter(kv.Key, kv.Value); + +using FeedIterator iterator = container.GetItemQueryIterator(query); +var results = new List(); +while (iterator.HasMoreResults) +{ + FeedResponse page = await iterator.ReadNextAsync(); + results.AddRange(page); +} +``` + +### Combining with ORDER BY / TOP + +`CosmosFilterExpression` only produces the WHERE fragment — compose the rest of the SQL yourself: + +```csharp +var queryText = $"SELECT TOP 20 * FROM c WHERE {f.WhereClause} ORDER BY c.CreatedAt DESC"; +var query = new QueryDefinition(queryText); +foreach (var kv in f.Parameters) + query = query.WithParameter(kv.Key, kv.Value); +``` + +### Handling the empty `In` list case + +```csharp +var regionCodes = GetRegionCodesFromRequest(); // might be empty + +var builder = new ValiFlow().EqualTo(x => x.Status, "Active"); + +if (regionCodes.Count > 0) + builder = builder.And(builder, new ValiFlow().In(x => x.RegionCode, regionCodes)); + +CosmosFilterExpression f = builder.ToCosmosDb(); // safe — In() only called when the list is non-empty +``` diff --git a/docs/en/vali-flow-nosql-couchbase.md b/docs/en/vali-flow-nosql-couchbase.md new file mode 100644 index 0000000..7d97fa9 --- /dev/null +++ b/docs/en/vali-flow-nosql-couchbase.md @@ -0,0 +1,266 @@ +# Vali-Flow.NoSql.Couchbase — Complete Reference + +## Table of Contents + +1. [Overview](#overview) +2. [Installation](#installation) +3. [Quick Start](#quick-start) +4. [Extension Methods](#extension-methods) +5. [CouchbaseFilterExpression](#couchbasefilterexpression) +6. [Supported Operations](#supported-operations) +7. [Type Mapping](#type-mapping) +8. [Custom Value Converter](#custom-value-converter) +9. [Limitations](#limitations) +10. [Full Example](#full-example) + +--- + +## Overview + +**Vali-Flow.NoSql.Couchbase** translates a `ValiFlow` expression tree into a Couchbase N1QL (SQL++) WHERE clause fragment together with a named-parameter dictionary. + +Unlike MongoDB, Elasticsearch, or DynamoDB, Couchbase's N1QL is plain parameterized text — the same approach as SQL. There is no "native" filter object to build (no `BsonDocument`, no `AttributeValue`), so the output is simply a `string` fragment plus a `Dictionary` of named parameters (`$p0`, `$p1`, …). + +The package depends only on `Vali-Flow.NoSql`. **It has no dependency on the Couchbase .NET SDK** — it is a pure text/parameter builder with no connection or execution concerns. Running the resulting query against a cluster is entirely up to the consumer. + +--- + +## Installation + +```bash +dotnet add package Vali-Flow.NoSql.Couchbase +``` + +`Vali-Flow.Core` is included as a transitive dependency. + +--- + +## Quick Start + +```csharp +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Couchbase.Extensions; +using Vali_Flow.NoSql.Couchbase.Models; + +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Active") + .GreaterThan(x => x.Total, 100m); + +CouchbaseFilterExpression f = filter.ToCouchbase(); + +var query = $"SELECT * FROM `orders` WHERE {f.WhereClause}"; + +var options = new QueryOptions(); +foreach (var (name, value) in f.Parameters) + options.Parameter(name, value); + +IQueryResult result = await cluster.QueryAsync(query, options); +``` + +--- + +## Extension Methods + +Both overloads are in `Vali_Flow.NoSql.Couchbase.Extensions.ValiFlowCouchbaseExtensions`. + +### `ToCouchbase(this ValiFlow flow, Func? customConverter = null)` + +Translates the conditions accumulated in a `ValiFlow` builder into a `CouchbaseFilterExpression`. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `flow` | `ValiFlow` | Yes | The builder containing the conditions. | +| `customConverter` | `Func?` | No | Hook for mapping CLR types not handled by the built-in switch. Called **before** the default conversion. Return `null` to fall through to it. | + +Throws `ArgumentNullException` if `flow` is `null`. + +**Returns:** `CouchbaseFilterExpression` — combine `WhereClause` with a full N1QL statement and bind `Parameters`. + +### `ToCouchbase(this Expression> expression, Func? customConverter = null)` + +Same translation for a pre-built `Expression>`. + +```csharp +Expression> expr = u => u.IsActive && u.Age >= 21; +CouchbaseFilterExpression f = expr.ToCouchbase(); +``` + +Throws `ArgumentNullException` if `expression` is `null`. + +--- + +## CouchbaseFilterExpression + +`CouchbaseFilterExpression` is a sealed class that encapsulates the two values a N1QL query needs: + +| Property | Type | Description | +|----------|------|-------------| +| `WhereClause` | `string` | The WHERE clause fragment, **without** the leading `WHERE` keyword, e.g. `` "`Name` = $p0" ``. | +| `Parameters` | `IReadOnlyDictionary` | Named N1QL parameters (`$p0`, `$p1`, …) to bind to the query. | + +The translator generates sequential `$p0`, `$p1`, … placeholders for every literal value in the filter, regardless of node type (equality, comparison, `LIKE` pattern, or `IN` list). + +--- + +## Supported Operations + +| ValiFlow method | IR node | N1QL fragment | +|----------------|---------|----------------| +| `.EqualTo(x => x.Field, v)` | `EqualNode(IsNegated: false)` | `` `Field` = $p0 `` | +| `.NotEqualTo(x => x.Field, v)` | `EqualNode(IsNegated: true)` | `` `Field` <> $p0 `` | +| `.GreaterThan(x => x.Field, v)` | `ComparisonNode(GT)` | `` `Field` > $p0 `` | +| `.GreaterThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(GTE)` | `` `Field` >= $p0 `` | +| `.LessThan(x => x.Field, v)` | `ComparisonNode(LT)` | `` `Field` < $p0 `` | +| `.LessThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(LTE)` | `` `Field` <= $p0 `` | +| `.Contains(x => x.Field, "txt")` | `LikeNode(Contains)` | `` `Field` LIKE $p0 `` with `$p0 = "%txt%"` | +| `.StartsWith(x => x.Field, "pre")` | `LikeNode(StartsWith)` | `` `Field` LIKE $p0 `` with `$p0 = "pre%"` | +| `.EndsWith(x => x.Field, "suf")` | `LikeNode(EndsWith)` | `` `Field` LIKE $p0 `` with `$p0 = "%suf"` | +| `.In(x => x.Field, list)` | `InNode` | `` `Field` IN $p0 `` with `$p0` bound to the **whole array** | +| `.IsNull(x => x.Field)` | `NullNode(IsNull)` | `` `Field` IS NULL `` | +| `.IsNotNull(x => x.Field)` | `NullNode(IsNotNull)` | `` `Field` IS NOT NULL `` | +| `.And(a, b)` | `AndNode` | `(a AND b)` | +| `.Or(a, b)` | `OrNode` | `(a OR b)` | +| `.Not(inner)` | `NotNode` | `NOT (inner)` | + +Identifiers are wrapped in backticks (`` `Field` ``) — the N1QL/MySQL quoting convention. + +Note the `In` row: unlike DynamoDB (which expands to `#f0 IN (:v0, :v1, …)`), Couchbase binds the **entire list as a single array parameter** — `` `Field` IN $p0 `` with `Parameters["$p0"]` set to a `List`. N1QL evaluates `IN` against the bound array directly. + +`EndsWith` is fully supported here — unlike DynamoDB, N1QL's `LIKE` has no restriction on trailing wildcards. + +--- + +## Type Mapping + +The built-in value-resolution switch handles these CLR types: + +| CLR type | Parameter value produced | +|----------|---------------------------| +| `null` | `null` | +| `bool` | `b` (unchanged) | +| `string` | `s` (unchanged) | +| `int` | `i` (unchanged) | +| `long` | `l` (unchanged) | +| `double` | `d` (unchanged) | +| `float` | `(double)f` | +| `decimal` | `m.ToString(CultureInfo.InvariantCulture)` — bound as a **string**, not a native number | +| `Guid` | `g.ToString()` | +| `Enum` | `Convert.ToInt64(e)` — the underlying integer value | +| anything else | `v.ToString()` | + +The `decimal → string` conversion is deliberate: N1QL/JSON numbers are IEEE-754 doubles, which lose precision for money-shaped values. If your Couchbase schema stores the field as a native N1QL number, cast in the query (`TONUMBER($p0)`) or supply a `customConverter` that returns the raw `decimal` (JSON-serializable as a number by the SDK). + +--- + +## Custom Value Converter + +Use `customConverter` when your domain types are not in the table above, or when you need a different parameter representation than the default. + +The converter is called **before** the built-in switch. Return `null` to let the default handle the value. + +```csharp +// Domain type +record Money(decimal Amount, string Currency); + +// Converter: store Money as a native number (amount only) +CouchbaseFilterExpression f = new ValiFlow() + .GreaterThan(x => x.Total, new Money(500m, "USD")) + .ToCouchbase(value => + { + if (value is Money m) + return m.Amount; // bound as a native decimal/number, not a string + return null; + }); +``` + +Storing a `DateTimeOffset` as an ISO-8601 string: + +```csharp +CouchbaseFilterExpression f = new ValiFlow() + .GreaterThan(x => x.StartsAt, DateTimeOffset.UtcNow) + .ToCouchbase(value => + { + if (value is DateTimeOffset dto) + return dto.ToString("O"); + return null; + }); +``` + +--- + +## Limitations + +| Limitation | Detail | +|-----------|--------| +| No Couchbase SDK dependency | This package only builds `WhereClause` + `Parameters`. Unlike `Vali-Flow.NoSql.Mongo`, `.Elasticsearch`, or `.DynamoDB` — which depend on and return objects from their respective provider SDKs — `Vali-Flow.NoSql.Couchbase` depends on nothing Couchbase-specific. You are responsible for wiring the result into a real query via the official `CouchbaseNetClient` SDK (or any other client capable of running N1QL). | +| Empty `In` list | Throws `InvalidOperationException`: *"IN condition with empty list is not supported in Couchbase N1QL expressions. Filter the empty case before building the query."* Filter it out before calling `.In(...)`. | +| `decimal` bound as string | See [Type Mapping](#type-mapping). Supply a `customConverter` if you need a native numeric parameter. | +| Comparison operators | Only `GreaterThan`, `GreaterThanOrEqualTo`, `LessThan`, `LessThanOrEqualTo` are mapped. Any other `ComparisonOp` throws `NotSupportedException`. | +| `LikeOp` coverage | Only `Contains`, `StartsWith`, `EndsWith` are mapped. Any other `LikeOp` throws `NotSupportedException`. | + +--- + +## Full Example + +A realistic filter combining equality, range, membership, and null checks, executed against a real Couchbase cluster with the official SDK: + +```csharp +using Couchbase; +using Couchbase.Query; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Couchbase.Extensions; +using Vali_Flow.NoSql.Couchbase.Models; + +var cluster = await Cluster.ConnectAsync( + "couchbase://localhost", + "Administrator", + "password"); + +// Build the filter +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Processing") + .GreaterThanOrEqualTo(x => x.Total, 100m) + .LessThan(x => x.Total, 5000m) + .In(x => x.RegionCode, new[] { "US", "CA", "MX" }) + .IsNotNull(x => x.CustomerId); + +CouchbaseFilterExpression f = filter.ToCouchbase(); + +// f.WhereClause: +// "(((`Status` = $p0 AND (`Total` >= $p1 AND (`Total` < $p2 AND (`RegionCode` IN $p3 AND `CustomerId` IS NOT NULL)))))" + +var query = $"SELECT META(o).id, o.* FROM `orders` o WHERE {f.WhereClause}"; + +var options = new QueryOptions(); +foreach (var (name, value) in f.Parameters) + options.Parameter(name, value); + +// NOTE: QueryOptions.Parameter(string, object) is the CouchbaseNetClient SDK's +// named-parameter binding API as of the Couchbase .NET SDK 3.x line. Verify the +// exact overload against the SDK version you reference — some versions expose +// a JObject-based NamedParameters setter instead. +IQueryResult result = await cluster.QueryAsync(query, options); + +await foreach (var order in result) +{ + Console.WriteLine(order.Status); +} +``` + +### Handling a native-numeric `decimal` with a custom converter + +```csharp +// By default decimals bind as strings (see Type Mapping). Override when the +// bucket schema stores Total as a native N1QL number. +var filter = new ValiFlow() + .GreaterThan(x => x.Total, 100m); + +CouchbaseFilterExpression f = filter.ToCouchbase(value => value is decimal d ? (object)d : null); + +var query = $"SELECT * FROM `orders` WHERE {f.WhereClause}"; +var options = new QueryOptions(); +foreach (var (name, value) in f.Parameters) + options.Parameter(name, value); + +IQueryResult result = await cluster.QueryAsync(query, options); +``` diff --git a/docs/en/vali-flow-nosql-firestore.md b/docs/en/vali-flow-nosql-firestore.md new file mode 100644 index 0000000..dc3493f --- /dev/null +++ b/docs/en/vali-flow-nosql-firestore.md @@ -0,0 +1,234 @@ +# Vali-Flow.NoSql.Firestore — Complete Reference + +## Table of Contents + +1. [Overview](#overview) +2. [Installation](#installation) +3. [Quick Start](#quick-start) +4. [Extension Methods](#extension-methods) +5. [Supported Operations](#supported-operations) +6. [Type Mapping](#type-mapping) +7. [Custom Value Converter](#custom-value-converter) +8. [Limitations](#limitations) +9. [Full Example](#full-example) + +--- + +## Overview + +**Vali-Flow.NoSql.Firestore** translates a `ValiFlow` expression tree into a native `Google.Cloud.Firestore.Filter`. Unlike the SQL/MongoDB adapters, this one does not build a document or string — it produces the actual `Filter` object from the official `Google.Cloud.Firestore` SDK (v4.4.0), so the output is accepted directly by `Query.Where(filter)` / `CollectionReference.Where(filter)` with no cast, wrapping, or serialization step. + +Because the adapter is bound to the real SDK type, it inherits the real SDK's capabilities — and its real gaps. Firestore's query engine is intentionally limited compared to a general-purpose database: there is no pattern-matching operator and no way to negate an arbitrary sub-filter. Both limitations are enforced in code (see [Limitations](#limitations)) rather than silently producing an incorrect filter. + +--- + +## Installation + +```bash +dotnet add package Vali-Flow.NoSql.Firestore +``` + +`Vali-Flow.NoSql` (the IR layer) is included as a transitive dependency. `Google.Cloud.Firestore` 4.4.0 is a direct dependency — this package does not try to abstract it away. + +--- + +## Quick Start + +```csharp +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Firestore.Extensions; +using Google.Cloud.Firestore; + +var filter = new ValiFlow() + .EqualTo(x => x.IsActive, true) + .GreaterThan(x => x.Age, 18); + +Filter firestoreFilter = filter.ToFirestore(); + +FirestoreDb firestoreDb = FirestoreDb.Create("my-project-id"); +CollectionReference collection = firestoreDb.Collection("users"); +Query query = collection.Where(firestoreFilter); +QuerySnapshot snapshot = await query.GetSnapshotAsync(); + +foreach (DocumentSnapshot doc in snapshot.Documents) +{ + var user = doc.ConvertTo(); +} +``` + +--- + +## Extension Methods + +Both overloads live in `Vali_Flow.NoSql.Firestore.Extensions.ValiFlowFirestoreExtensions`. + +### `ToFirestore(this ValiFlow flow, Func? customConverter = null)` + +Translates the conditions accumulated in a `ValiFlow` builder into a native `Filter`. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `flow` | `ValiFlow` | Yes | The builder containing the conditions. Throws `ArgumentNullException` if `null`. | +| `customConverter` | `Func?` | No | Hook for mapping CLR types not handled by the built-in switch. Return `null` to fall through to the default conversion. Scoped to this call only (thread-safe). | + +**Returns:** `Filter` — pass directly to `Query.Where(filter)`. + +### `ToFirestore(this Expression> expression, Func? customConverter = null)` + +Same translation for a pre-built `Expression>`. + +```csharp +Expression> expr = o => o.Status == "Pending" && o.Total > 50m; +Filter filter = expr.ToFirestore(); +``` + +Both overloads are thin wrappers over `FirestoreFilterTranslator.Translate(IConditionNode, Func?)` — the `ValiFlow` overload calls `flow.ToNoSqlIR()` first, the expression overload calls `expression.ToNoSqlIR()` first. + +--- + +## Supported Operations + +| ValiFlow method | IR node | Firestore `Filter` call | +|----------------|---------|--------------------------| +| `.EqualTo(x => x.Field, v)` | `EqualNode(IsNegated: false)` | `Filter.EqualTo(field, value)` | +| `.NotEqualTo(x => x.Field, v)` | `EqualNode(IsNegated: true)` | `Filter.NotEqualTo(field, value)` | +| `.GreaterThan(x => x.Field, v)` | `ComparisonNode(GreaterThan)` | `Filter.GreaterThan(field, value)` | +| `.GreaterThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(GreaterThanOrEqual)` | `Filter.GreaterThanOrEqualTo(field, value)` | +| `.LessThan(x => x.Field, v)` | `ComparisonNode(LessThan)` | `Filter.LessThan(field, value)` | +| `.LessThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(LessThanOrEqual)` | `Filter.LessThanOrEqualTo(field, value)` | +| `.In(x => x.Field, list)` | `InNode` | `Filter.InArray(field, values)` | +| `.IsNull(x => x.Field)` | `NullNode(IsNull)` | `Filter.EqualTo(field, null)` | +| `.IsNotNull(x => x.Field)` | `NullNode(IsNotNull)` | `Filter.NotEqualTo(field, null)` | +| `.And(a, b)` | `AndNode` | `Filter.And(left, right)` | +| `.Or(a, b)` | `OrNode` | `Filter.Or(left, right)` | +| `.Contains` / `.StartsWith` / `.EndsWith` | `LikeNode` | **throws** `NotSupportedException` | +| `.Not(inner)` | `NotNode` | **throws** `NotSupportedException` | + +`And`/`Or` nest recursively, exactly mirroring the shape of the IR tree — there is no flattening into a single `Filter.And(a, b, c, ...)` call even if the source expression chains more than two conditions; each binary node becomes one nested `Filter.And`/`Filter.Or` call. + +--- + +## Type Mapping + +The built-in switch inside `FirestoreFilterTranslator` (method `ToValue`) handles these CLR types before handing the value to `Filter.*`: + +| CLR type | Value passed to `Filter.*` | +|----------|------------------------------| +| `null` | `null` | +| `Enum` | `int` (via `Convert.ToInt32(e)`) | +| `DateTimeOffset` | `Timestamp.FromDateTimeOffset(dto)` | +| `DateTime` | `Timestamp.FromDateTime(...)` — converted to UTC first if `dt.Kind != DateTimeKind.Utc` | +| anything else (`string`, `int`, `long`, `double`, `bool`, `decimal`, ...) | passed through unchanged — the Firestore SDK serializes these natively | + +Resolution order: `customConverter` (if provided) runs first via `ConditionValueResolver.Resolve`; if it returns `null`, the built-in switch above applies. + +--- + +## Custom Value Converter + +Use `customConverter` for domain types the built-in switch doesn't know about, or to override a default (for example, storing a `decimal` as `double` instead of letting the SDK serialize it as-is). + +The converter runs **before** the built-in switch. Return `null` to let the default handle the value. + +```csharp +// Domain type +record Money(decimal Amount, string Currency); + +// Converter: store Money as a double amount +Filter filter = new ValiFlow() + .GreaterThan(x => x.Price, new Money(100m, "USD")) + .ToFirestore(value => + { + if (value is Money m) + return (double)m.Amount; + return null; // fall through for everything else + }); +``` + +--- + +## Limitations + +Firestore is the provider with the most query-engine gaps among the Vali-Flow NoSql adapters, and this package does **not** hide that behind a silently-wrong filter — unsupported nodes throw immediately at translation time. + +### 1. No pattern matching — `LikeNode` (Contains / StartsWith / EndsWith) + +Firestore has no LIKE, regex, or substring query operator. All three `LikeNode` variants throw, with the specific `LikeOp` named in the message: + +```csharp +new ValiFlow().Contains(x => x.Name, "ann").ToFirestore(); +// throws NotSupportedException: +// "Firestore does not support pattern-matching queries (LikeOp.Contains). +// There is no regex/LIKE query operator — filter client-side or use a +// dedicated search index (e.g. Algolia/Elasticsearch) instead." +``` + +The same happens for `LikeOp.StartsWith` and `LikeOp.EndsWith` — only the operator name in the message changes. **Workaround:** filter the result set client-side after fetching, or integrate a dedicated search index (Algolia, Elasticsearch, Typesense) for text search use cases. + +### 2. No generic NOT over an arbitrary sub-expression — `NotNode` + +The Firestore SDK does not expose a "negate this filter" composition — there is no `Filter.Not(filter)`. Any `.Not(inner)` call throws unconditionally, regardless of what `inner` is: + +```csharp +new ValiFlow().Not(f => f.EqualTo(x => x.IsActive, true)).ToFirestore(); +// throws NotSupportedException: +// "Firestore does not support a generic NOT filter over an arbitrary +// sub-expression. The SDK only exposes field-level negations +// (NotEqualTo/NotInArray) via Filter, which are already handled when +// the negated node is an EqualNode/InNode directly." +``` + +**Workaround:** don't wrap in `.Not(...)`. Express the negation at the field level instead — use `.NotEqualTo(x => x.Field, v)` directly (which becomes `EqualNode.IsNegated = true` → `Filter.NotEqualTo`), rather than `.Not(f => f.EqualTo(x => x.Field, v))`. + +### 3. `.In(...)` has no negated counterpart yet + +The SDK exposes `Filter.NotInArray(field, values)`, and the translator's doc comments acknowledge it — but `InNode` in the current IR has no `IsNegated` flag (unlike `EqualNode`), so there is currently no `ValiFlow` method that reaches `Filter.NotInArray`. This is not a thrown exception, just an operation that is not reachable yet from the fluent API against this provider. + +### 4. Composite/nested `AND`/`OR` map 1:1, with no flattening + +Not a missing feature, but worth knowing: chaining three or more conditions produces nested `Filter.And(a, Filter.And(b, c))` rather than a single flat `Filter.And(a, b, c)`. Firestore accepts nested composite filters, so this is semantically equivalent — just worth knowing if you inspect the generated `Filter` for debugging. + +--- + +## Full Example + +A realistic filter combining equality, range, membership, and null checks, executed against a real `FirestoreDb`: + +```csharp +using Google.Cloud.Firestore; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Firestore.Extensions; + +// Build the filter +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Processing") + .GreaterThanOrEqualTo(x => x.Total, 100m) + .LessThan(x => x.Total, 5000m) + .In(x => x.RegionCode, new[] { "US", "CA", "MX" }) + .IsNotNull(x => x.CustomerId); + +Filter firestoreFilter = filter.ToFirestore(); + +// Execute with the real SDK +FirestoreDb firestoreDb = FirestoreDb.Create("my-project-id"); +CollectionReference collection = firestoreDb.Collection("orders"); +Query query = collection.Where(firestoreFilter).Limit(50); + +QuerySnapshot snapshot = await query.GetSnapshotAsync(); + +foreach (DocumentSnapshot doc in snapshot.Documents) +{ + Order order = doc.ConvertTo(); +} +``` + +### Using the expression overload + +```csharp +Expression> activeAndAffordable = + p => p.IsActive && p.Price < 200m; + +Filter filter = activeAndAffordable.ToFirestore(); +Query query = firestoreDb.Collection("products").Where(filter); +var snapshot = await query.GetSnapshotAsync(); +``` diff --git a/docs/es/architecture/overview.md b/docs/es/architecture/overview.md index d7fa2f5..a6acbd3 100644 --- a/docs/es/architecture/overview.md +++ b/docs/es/architecture/overview.md @@ -143,7 +143,7 @@ Vali-Flow.sln └── Vali-Flow.NoSql.DynamoDB.Tests/ Tests de DynamoDB ``` -Todos los paquetes apuntan a `net8.0` y `net9.0`. +Todos los paquetes apuntan a `net8.0` y `net9.0`, y tambien corren sin modificaciones en **.NET 10** gracias a la compatibilidad hacia adelante de .NET. --- diff --git a/docs/es/guides/getting-started.md b/docs/es/guides/getting-started.md index ab92d12..adf6a56 100644 --- a/docs/es/guides/getting-started.md +++ b/docs/es/guides/getting-started.md @@ -4,7 +4,7 @@ Esta guía te lleva a través de la instalación y uso del ecosistema Vali-Flow ## Requisitos previos -- .NET 8 o .NET 9 +- .NET 8 o .NET 9 (tambien corre en .NET 10 por compatibilidad hacia adelante) - Un proyecto C# (cualquier tipo: Web API, consola, proyecto de tests, etc.) --- diff --git a/docs/es/internal/benchmarks.md b/docs/es/internal/benchmarks.md index 648bbcf..cdd1e92 100644 --- a/docs/es/internal/benchmarks.md +++ b/docs/es/internal/benchmarks.md @@ -1,6 +1,6 @@ # Benchmarks de Vali-Flow -El proyecto `Vali-Flow.Benchmarks` mide el rendimiento del evaluador InMemory y del constructor SQL usando [BenchmarkDotNet](https://benchmarkdotnet.org/). +El proyecto `Vali-Flow.Benchmarks` mide el rendimiento del evaluador InMemory, del constructor SQL y del evaluador EF Core usando [BenchmarkDotNet](https://benchmarkdotnet.org/). --- @@ -20,6 +20,7 @@ Para ejecutar una clase de benchmark específica: ```bash dotnet run --configuration Release -- --filter "*InMemoryFilter*" dotnet run --configuration Release -- --filter "*SqlBuilder*" +dotnet run --configuration Release -- --filter "*EfCore*" ``` --- @@ -45,6 +46,14 @@ Todos los benchmarks InMemory parametrizan sobre `N ∈ { 1 000, 10 000, 100 000 |-------|----------| | `SqlBuilderBenchmarks` | `SqlQueryBuilder` SELECT con JOINs, INSERT, UPDATE — solo el costo de construcción (sin round-trip a BD) | +### Evaluador EF Core + +Usa el proveedor **InMemory de EF Core** (`Microsoft.EntityFrameworkCore.InMemory`) — mide el overhead de `ValiFlowEvaluator`/`QuerySpecificationBuilder` (construcción de query + traducción LINQ), no I/O real de base de datos. Parametrizado sobre `N ∈ { 1 000, 10 000, 100 000 }`. + +| Clase | Qué mide | +|-------|----------| +| `EfCoreBenchmarks` | Filtro con `EvaluateQueryAsync` (baseline: LINQ crudo `.Where()` sobre el mismo `DbContext`), `EvaluatePagedAsync`, `EvaluateCountAsync` | + --- ## Interpretar los resultados @@ -76,8 +85,8 @@ BenchmarkDotNet reporta: ## Limitaciones conocidas -- **Sin benchmarks NoSQL** — los traductores `Vali-Flow.NoSql.*` no tienen benchmarks. La traducción es solo CPU (sin I/O) y los árboles son pequeños, por lo que el overhead esperado es sub-microsegundo. -- **Sin benchmarks EF Core** — el rendimiento de EF Core está dominado por el round-trip a la base de datos, no por la capa de Vali-Flow. El profiling debe hacerse con planes de query reales, no con microbenchmarks. +- **Sin benchmarks NoSQL** — los traductores `Vali-Flow.NoSql.*` (7 proveedores) no tienen benchmarks. La traducción es solo CPU (sin I/O) y los árboles son pequeños, por lo que el overhead esperado es sub-microsegundo. +- **Los benchmarks de EF Core miden construcción, no I/O real** — `EfCoreBenchmarks` usa el proveedor InMemory de EF Core, así que aísla el overhead de `ValiFlowEvaluator`/`QuerySpecificationBuilder`. El rendimiento real contra una base de datos está dominado por el round-trip y el plan de query, no por esta capa — para eso hace falta profiling contra un proveedor real. --- diff --git a/docs/es/vali-flow-ef-core.md b/docs/es/vali-flow-ef-core.md index 94f2958..2f12bd5 100644 --- a/docs/es/vali-flow-ef-core.md +++ b/docs/es/vali-flow-ef-core.md @@ -78,7 +78,7 @@ dotnet add package Vali-Flow **Requisitos** -- .NET 8 o superior +- .NET 8, 9 o 10 (compilado para net8.0/net9.0, corre sin modificaciones en .NET 10 por compatibilidad hacia adelante) - Entity Framework Core 8 o superior --- diff --git a/docs/es/vali-flow-nosql-cosmosdb.md b/docs/es/vali-flow-nosql-cosmosdb.md new file mode 100644 index 0000000..ffe314b --- /dev/null +++ b/docs/es/vali-flow-nosql-cosmosdb.md @@ -0,0 +1,261 @@ +# Vali-Flow.NoSql.CosmosDb — Referencia Completa + +## Tabla de Contenidos + +1. [Descripción general](#descripción-general) +2. [Instalación](#instalación) +3. [Inicio rápido](#inicio-rápido) +4. [Métodos de extensión](#métodos-de-extensión) +5. [CosmosFilterExpression](#cosmosfilterexpression) +6. [Operaciones soportadas](#operaciones-soportadas) +7. [Mapeo de tipos](#mapeo-de-tipos) +8. [Conversor de valores personalizado](#conversor-de-valores-personalizado) +9. [Limitaciones](#limitaciones) +10. [Ejemplo completo](#ejemplo-completo) + +--- + +## Descripción general + +**Vali-Flow.NoSql.CosmosDb** traduce un árbol de expresiones `ValiFlow` en un fragmento de cláusula WHERE de Azure Cosmos DB SQL API (un `string`) junto con el diccionario de parámetros necesario para vincularlo a un `QueryDefinition`. + +El paquete depende únicamente de `Vali-Flow.NoSql` (la capa de IR). A diferencia de los traductores de Mongo/Elasticsearch/DynamoDB, **no depende del SDK `Microsoft.Azure.Cosmos`** — es un constructor puro de string/parámetros, sin conexión ni preocupaciones de ejecución. El resultado se integra en tu propio `QueryDefinition`. + +--- + +## Instalación + +```bash +dotnet add package Vali-Flow.NoSql.CosmosDb +``` + +`Vali-Flow.Core` se incluye como dependencia transitiva. El SDK `Microsoft.Azure.Cosmos` **no** es una dependencia — agrégalo tú mismo para ejecutar la consulta. + +--- + +## Inicio rápido + +```csharp +using Microsoft.Azure.Cosmos; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.CosmosDb.Extensions; +using Vali_Flow.NoSql.CosmosDb.Models; + +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Active") + .GreaterThan(x => x.Total, 100m); + +CosmosFilterExpression f = filter.ToCosmosDb(); + +var queryText = $"SELECT * FROM c WHERE {f.WhereClause}"; +var query = new QueryDefinition(queryText); +foreach (var kv in f.Parameters) + query = query.WithParameter(kv.Key, kv.Value); + +using FeedIterator iterator = container.GetItemQueryIterator(query); +while (iterator.HasMoreResults) +{ + FeedResponse response = await iterator.ReadNextAsync(); + foreach (Order order in response) { /* ... */ } +} +``` + +--- + +## Métodos de extensión + +Ambas sobrecargas están en `Vali_Flow.NoSql.CosmosDb.Extensions.ValiFlowCosmosDbExtensions`. + +### `ToCosmosDb(this ValiFlow flow, Func? customConverter = null)` + +Traduce las condiciones acumuladas en un constructor `ValiFlow` en un `CosmosFilterExpression`. + +| Parámetro | Tipo | Requerido | Descripción | +|-----------|------|-----------|-------------| +| `flow` | `ValiFlow` | Sí | El constructor que contiene las condiciones. | +| `customConverter` | `Func?` | No | Hook para mapear tipos CLR no manejados por el switch incorporado hacia el valor crudo guardado en el diccionario de parámetros. Retorna `null` para caer al conversor por defecto. | + +**Retorna:** `CosmosFilterExpression` — agrega `WhereClause` a tu texto de consulta y vincula `Parameters` a un `QueryDefinition`. + +### `ToCosmosDb(this Expression> expression, Func? customConverter = null)` + +Misma traducción para una `Expression>` ya construida. + +```csharp +Expression> expr = u => u.IsActive && u.Age >= 21; +CosmosFilterExpression f = expr.ToCosmosDb(); +``` + +--- + +## CosmosFilterExpression + +`CosmosFilterExpression` es una clase sellada que encapsula los dos valores que necesita una consulta Cosmos SQL: + +| Propiedad | Tipo | Descripción | +|-----------|------|-------------| +| `WhereClause` | `string` | El fragmento de cláusula WHERE, **sin** la palabra clave `WHERE` al inicio, p.ej. `"c.Age > @p0"`. | +| `Parameters` | `IReadOnlyDictionary` | Mapea marcadores de posición (`@p0`, `@p1`, …) a sus valores crudos. | + +Las referencias a campos usan el alias estándar de contenedor de Cosmos SQL `c` (p.ej. `c.Status`), por lo que no existe una capa de marcadores de nombre de atributo como los `#f0` de DynamoDB — solo se generan marcadores de valor. + +`Parameters` se usa directamente con `QueryDefinition.WithParameter(name, value)` dentro de un `foreach` — no se necesita llamar a `.ToDictionary()`, ya que `WithParameter` del SDK recibe un par clave/valor a la vez en lugar de un diccionario completo como argumento del constructor. + +--- + +## Operaciones soportadas + +| Método ValiFlow | Nodo IR | Fragmento Cosmos SQL | +|----------------|---------|---------------------| +| `.EqualTo(x => x.Field, v)` | `EqualNode(IsNegated: false)` | `c.Field = @p0` | +| `.NotEqualTo(x => x.Field, v)` | `EqualNode(IsNegated: true)` | `c.Field != @p0` | +| `.GreaterThan(x => x.Field, v)` | `ComparisonNode(GT)` | `c.Field > @p0` | +| `.GreaterThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(GTE)` | `c.Field >= @p0` | +| `.LessThan(x => x.Field, v)` | `ComparisonNode(LT)` | `c.Field < @p0` | +| `.LessThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(LTE)` | `c.Field <= @p0` | +| `.Contains(x => x.Field, "txt")` | `LikeNode(Contains)` | `CONTAINS(c.Field, @p0)` | +| `.StartsWith(x => x.Field, "pre")` | `LikeNode(StartsWith)` | `STARTSWITH(c.Field, @p0)` | +| `.EndsWith(x => x.Field, "suf")` | `LikeNode(EndsWith)` | `ENDSWITH(c.Field, @p0)` | +| `.In(x => x.Field, list)` | `InNode` | `c.Field IN (@p0, @p1, …)` | +| `.IsNull(x => x.Field)` | `NullNode(IsNull)` | `IS_NULL(c.Field)` | +| `.IsNotNull(x => x.Field)` | `NullNode(IsNotNull)` | `NOT IS_NULL(c.Field)` | +| `.And(a, b)` | `AndNode` | `(a AND b)` | +| `.Or(a, b)` | `OrNode` | `(a OR b)` | +| `.Not(inner)` | `NotNode` | `NOT (inner)` | + +Los tres operadores `LikeNode` se mapean a funciones **nativas** de Cosmos SQL — a diferencia de DynamoDB, Cosmos soporta `ENDSWITH` directamente, así que no hace falta fallback del lado del cliente para ese caso. `IS_NULL` también es nativo — es una verificación real de nulo sobre el documento JSON, no una verificación de existencia de atributo. + +--- + +## Mapeo de tipos + +El switch de conversión incorporado maneja estos tipos CLR: + +| Tipo CLR | Valor de parámetro producido | +|----------|-------------------------------| +| `null` | `null` | +| `bool` | `b` (tal cual) | +| `string` | `s` (tal cual) | +| `int` | `i` (tal cual) | +| `long` | `l` (tal cual) | +| `double` | `d` (tal cual) | +| `float` | `f` (tal cual) | +| `decimal` | `m` (tal cual) | +| `Guid` | `g.ToString()` | +| `Enum` | valor subyacente como `long` (InvariantCulture) | +| cualquier otro | `v.ToString()` | + +A diferencia del wrapper `AttributeValue` de DynamoDB, los parámetros de Cosmos son valores CLR planos — `QueryDefinition.WithParameter` los acepta directamente y la API SQL de Cosmos maneja el tipado nativo de JSON (números, strings, booleanos) por su cuenta. + +--- + +## Conversor de valores personalizado + +Usa `customConverter` cuando tus tipos de dominio no están en la tabla anterior o cuando necesitas un valor crudo distinto al que produce el conversor por defecto. + +El conversor se llama **antes** del switch incorporado. Retorna `null` para dejar que el default maneje el valor. + +```csharp +// Tipo de dominio +record Money(decimal Amount, string Currency); + +// Conversor: almacena Money como número (solo el monto) +CosmosFilterExpression f = new ValiFlow() + .GreaterThan(x => x.Total, new Money(500m, "USD")) + .ToCosmosDb(value => + { + if (value is Money m) + return m.Amount; + return null; + }); +``` + +Almacenando un `DateTimeOffset` como cadena ISO-8601: + +```csharp +CosmosFilterExpression f = new ValiFlow() + .GreaterThan(x => x.StartsAt, DateTimeOffset.UtcNow) + .ToCosmosDb(value => + { + if (value is DateTimeOffset dto) + return dto.ToString("O"); + return null; + }); +``` + +--- + +## Limitaciones + +| Limitación | Detalle | +|-----------|---------| +| Sin dependencia del SDK de Cosmos | Este paquete solo produce `WhereClause` + `Parameters`. No construye ni ejecuta un `QueryDefinition`, no abre un `Container`, ni recorre un `FeedIterator` — eso queda enteramente a cargo del consumidor, a diferencia de los traductores de Mongo/Elasticsearch/DynamoDB que apuntan más directamente a los tipos nativos de request/filtro de su SDK. | +| Lista `In` vacía | Lanza `InvalidOperationException`. Cosmos DB SQL no acepta una lista `IN (...)` vacía. Filtra el caso vacío antes de construir la consulta. | +| Sin límite de tamaño impuesto en `In` | Este paquete no limita la cantidad de valores en una lista `In` (a diferencia del límite de 100 valores del SDK de DynamoDB). Listas muy grandes igual cuentan contra los límites propios de Cosmos DB de longitud y complejidad de la consulta — mantén las listas en un tamaño razonable. | +| Un marcador por valor en `In` | `IN (@p0, @p1, @p2, …)` — Cosmos SQL no acepta un único parámetro de tipo array para `IN`, así que cada valor recibe su propio marcador, igual que el resto de los parámetros del filtro. | + +--- + +## Ejemplo completo + +Un filtro realista que combina igualdad, rango, membresía y verificaciones de nulos, aplicado a través del SDK `Microsoft.Azure.Cosmos`: + +```csharp +using Microsoft.Azure.Cosmos; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.CosmosDb.Extensions; +using Vali_Flow.NoSql.CosmosDb.Models; + +CosmosClient client = new CosmosClient(connectionString); +Container container = client.GetContainer("myDb", "Orders"); + +// Construir el filtro +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Processing") + .GreaterThanOrEqualTo(x => x.Total, 100m) + .LessThan(x => x.Total, 5000m) + .In(x => x.RegionCode, new[] { "US", "CA", "MX" }) + .IsNotNull(x => x.CustomerId); + +CosmosFilterExpression f = filter.ToCosmosDb(); + +// f.WhereClause: +// "(((c.Status = @p0 AND c.Total >= @p1) AND c.Total < @p2) AND c.RegionCode IN (@p3, @p4, @p5)) AND NOT IS_NULL(c.CustomerId)" + +var queryText = $"SELECT * FROM c WHERE {f.WhereClause}"; +var query = new QueryDefinition(queryText); +foreach (var kv in f.Parameters) + query = query.WithParameter(kv.Key, kv.Value); + +using FeedIterator iterator = container.GetItemQueryIterator(query); +var results = new List(); +while (iterator.HasMoreResults) +{ + FeedResponse page = await iterator.ReadNextAsync(); + results.AddRange(page); +} +``` + +### Combinando con ORDER BY / TOP + +`CosmosFilterExpression` solo produce el fragmento WHERE — compón el resto del SQL tú mismo: + +```csharp +var queryText = $"SELECT TOP 20 * FROM c WHERE {f.WhereClause} ORDER BY c.CreatedAt DESC"; +var query = new QueryDefinition(queryText); +foreach (var kv in f.Parameters) + query = query.WithParameter(kv.Key, kv.Value); +``` + +### Manejando el caso de lista `In` vacía + +```csharp +var regionCodes = GetRegionCodesFromRequest(); // puede venir vacía + +var builder = new ValiFlow().EqualTo(x => x.Status, "Active"); + +if (regionCodes.Count > 0) + builder = builder.And(builder, new ValiFlow().In(x => x.RegionCode, regionCodes)); + +CosmosFilterExpression f = builder.ToCosmosDb(); // seguro — In() solo se llama cuando la lista no está vacía +``` diff --git a/docs/es/vali-flow-nosql-couchbase.md b/docs/es/vali-flow-nosql-couchbase.md new file mode 100644 index 0000000..6b9b1ea --- /dev/null +++ b/docs/es/vali-flow-nosql-couchbase.md @@ -0,0 +1,266 @@ +# Vali-Flow.NoSql.Couchbase — Referencia Completa + +## Tabla de Contenidos + +1. [Descripción general](#descripción-general) +2. [Instalación](#instalación) +3. [Inicio rápido](#inicio-rápido) +4. [Métodos de extensión](#métodos-de-extensión) +5. [CouchbaseFilterExpression](#couchbasefilterexpression) +6. [Operaciones soportadas](#operaciones-soportadas) +7. [Mapeo de tipos](#mapeo-de-tipos) +8. [Conversor de valores personalizado](#conversor-de-valores-personalizado) +9. [Limitaciones](#limitaciones) +10. [Ejemplo completo](#ejemplo-completo) + +--- + +## Descripción general + +**Vali-Flow.NoSql.Couchbase** traduce un árbol de expresiones `ValiFlow` en un fragmento de cláusula WHERE de N1QL (SQL++) de Couchbase, junto con un diccionario de parámetros con nombre. + +A diferencia de MongoDB, Elasticsearch o DynamoDB, el N1QL de Couchbase es texto parametrizado plano — el mismo enfoque que SQL. No existe un objeto de filtro "nativo" para construir (no hay `BsonDocument`, no hay `AttributeValue`): el resultado es simplemente un `string` más un `Dictionary` de parámetros con nombre (`$p0`, `$p1`, …). + +El paquete depende únicamente de `Vali-Flow.NoSql`. **No tiene ninguna dependencia del SDK .NET de Couchbase** — es un constructor puro de texto/parámetros, sin preocupaciones de conexión ni de ejecución. Ejecutar la consulta resultante contra un cluster queda enteramente del lado del consumidor. + +--- + +## Instalación + +```bash +dotnet add package Vali-Flow.NoSql.Couchbase +``` + +`Vali-Flow.Core` se incluye como dependencia transitiva. + +--- + +## Inicio rápido + +```csharp +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Couchbase.Extensions; +using Vali_Flow.NoSql.Couchbase.Models; + +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Active") + .GreaterThan(x => x.Total, 100m); + +CouchbaseFilterExpression f = filter.ToCouchbase(); + +var query = $"SELECT * FROM `orders` WHERE {f.WhereClause}"; + +var options = new QueryOptions(); +foreach (var (name, value) in f.Parameters) + options.Parameter(name, value); + +IQueryResult result = await cluster.QueryAsync(query, options); +``` + +--- + +## Métodos de extensión + +Ambas sobrecargas están en `Vali_Flow.NoSql.Couchbase.Extensions.ValiFlowCouchbaseExtensions`. + +### `ToCouchbase(this ValiFlow flow, Func? customConverter = null)` + +Traduce las condiciones acumuladas en un constructor `ValiFlow` en un `CouchbaseFilterExpression`. + +| Parámetro | Tipo | Requerido | Descripción | +|-----------|------|-----------|-------------| +| `flow` | `ValiFlow` | Sí | El constructor que contiene las condiciones. | +| `customConverter` | `Func?` | No | Hook para mapear tipos CLR no manejados por el switch incorporado. Se invoca **antes** de la conversión por defecto. Retorna `null` para caer en ella. | + +Lanza `ArgumentNullException` si `flow` es `null`. + +**Retorna:** `CouchbaseFilterExpression` — combina `WhereClause` con una sentencia N1QL completa y enlaza `Parameters`. + +### `ToCouchbase(this Expression> expression, Func? customConverter = null)` + +Misma traducción para una `Expression>` ya construida. + +```csharp +Expression> expr = u => u.IsActive && u.Age >= 21; +CouchbaseFilterExpression f = expr.ToCouchbase(); +``` + +Lanza `ArgumentNullException` si `expression` es `null`. + +--- + +## CouchbaseFilterExpression + +`CouchbaseFilterExpression` es una clase sellada que encapsula los dos valores que necesita una consulta N1QL: + +| Propiedad | Tipo | Descripción | +|-----------|------|-------------| +| `WhereClause` | `string` | El fragmento de cláusula WHERE, **sin** la palabra clave `WHERE` inicial, p.ej. `` "`Name` = $p0" ``. | +| `Parameters` | `IReadOnlyDictionary` | Parámetros N1QL con nombre (`$p0`, `$p1`, …) a enlazar en la consulta. | + +El traductor genera marcadores secuenciales `$p0`, `$p1`, … para cada valor literal del filtro, sin importar el tipo de nodo (igualdad, comparación, patrón de `LIKE` o lista de `IN`). + +--- + +## Operaciones soportadas + +| Método ValiFlow | Nodo IR | Fragmento N1QL | +|----------------|---------|----------------| +| `.EqualTo(x => x.Field, v)` | `EqualNode(IsNegated: false)` | `` `Field` = $p0 `` | +| `.NotEqualTo(x => x.Field, v)` | `EqualNode(IsNegated: true)` | `` `Field` <> $p0 `` | +| `.GreaterThan(x => x.Field, v)` | `ComparisonNode(GT)` | `` `Field` > $p0 `` | +| `.GreaterThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(GTE)` | `` `Field` >= $p0 `` | +| `.LessThan(x => x.Field, v)` | `ComparisonNode(LT)` | `` `Field` < $p0 `` | +| `.LessThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(LTE)` | `` `Field` <= $p0 `` | +| `.Contains(x => x.Field, "txt")` | `LikeNode(Contains)` | `` `Field` LIKE $p0 `` con `$p0 = "%txt%"` | +| `.StartsWith(x => x.Field, "pre")` | `LikeNode(StartsWith)` | `` `Field` LIKE $p0 `` con `$p0 = "pre%"` | +| `.EndsWith(x => x.Field, "suf")` | `LikeNode(EndsWith)` | `` `Field` LIKE $p0 `` con `$p0 = "%suf"` | +| `.In(x => x.Field, list)` | `InNode` | `` `Field` IN $p0 `` con `$p0` enlazado al **array completo** | +| `.IsNull(x => x.Field)` | `NullNode(IsNull)` | `` `Field` IS NULL `` | +| `.IsNotNull(x => x.Field)` | `NullNode(IsNotNull)` | `` `Field` IS NOT NULL `` | +| `.And(a, b)` | `AndNode` | `(a AND b)` | +| `.Or(a, b)` | `OrNode` | `(a OR b)` | +| `.Not(inner)` | `NotNode` | `NOT (inner)` | + +Los identificadores van entre backticks (`` `Field` ``) — la convención de quoting de N1QL/MySQL. + +Fijate en la fila de `In`: a diferencia de DynamoDB (que expande a `#f0 IN (:v0, :v1, …)`), Couchbase enlaza **toda la lista como un único parámetro array** — `` `Field` IN $p0 `` con `Parameters["$p0"]` apuntando a un `List`. N1QL evalúa el `IN` directamente contra el array enlazado. + +`EndsWith` está completamente soportado acá — a diferencia de DynamoDB, el `LIKE` de N1QL no tiene ninguna restricción sobre comodines al final. + +--- + +## Mapeo de tipos + +El switch de resolución de valores incorporado maneja estos tipos CLR: + +| Tipo CLR | Valor de parámetro producido | +|----------|-------------------------------| +| `null` | `null` | +| `bool` | `b` (sin cambios) | +| `string` | `s` (sin cambios) | +| `int` | `i` (sin cambios) | +| `long` | `l` (sin cambios) | +| `double` | `d` (sin cambios) | +| `float` | `(double)f` | +| `decimal` | `m.ToString(CultureInfo.InvariantCulture)` — se enlaza como **string**, no como número nativo | +| `Guid` | `g.ToString()` | +| `Enum` | `Convert.ToInt64(e)` — el valor entero subyacente | +| cualquier otro | `v.ToString()` | + +La conversión `decimal → string` es deliberada: los números de N1QL/JSON son doubles IEEE-754, que pierden precisión en valores con forma de dinero. Si tu esquema en Couchbase almacena el campo como un número N1QL nativo, castea en la consulta (`TONUMBER($p0)`) o pasá un `customConverter` que retorne el `decimal` crudo (serializable como número por el SDK). + +--- + +## Conversor de valores personalizado + +Usa `customConverter` cuando tus tipos de dominio no están en la tabla anterior, o cuando necesitas una representación de parámetro distinta a la por defecto. + +El conversor se llama **antes** del switch incorporado. Retorna `null` para dejar que el default maneje el valor. + +```csharp +// Tipo de dominio +record Money(decimal Amount, string Currency); + +// Conversor: almacena Money como número nativo (solo el monto) +CouchbaseFilterExpression f = new ValiFlow() + .GreaterThan(x => x.Total, new Money(500m, "USD")) + .ToCouchbase(value => + { + if (value is Money m) + return m.Amount; // se enlaza como decimal/número nativo, no como string + return null; + }); +``` + +Almacenando un `DateTimeOffset` como cadena ISO-8601: + +```csharp +CouchbaseFilterExpression f = new ValiFlow() + .GreaterThan(x => x.StartsAt, DateTimeOffset.UtcNow) + .ToCouchbase(value => + { + if (value is DateTimeOffset dto) + return dto.ToString("O"); + return null; + }); +``` + +--- + +## Limitaciones + +| Limitación | Detalle | +|-----------|---------| +| Sin dependencia del SDK de Couchbase | Este paquete solo construye `WhereClause` + `Parameters`. A diferencia de `Vali-Flow.NoSql.Mongo`, `.Elasticsearch` o `.DynamoDB` — que dependen de y retornan objetos de sus respectivos SDKs de proveedor —, `Vali-Flow.NoSql.Couchbase` no depende de nada específico de Couchbase. Vos sos responsable de conectar el resultado a una consulta real mediante el SDK oficial `CouchbaseNetClient` (o cualquier otro cliente capaz de ejecutar N1QL). | +| Lista `In` vacía | Lanza `InvalidOperationException`: *"IN condition with empty list is not supported in Couchbase N1QL expressions. Filter the empty case before building the query."* Filtrala antes de llamar a `.In(...)`. | +| `decimal` enlazado como string | Ver [Mapeo de tipos](#mapeo-de-tipos). Pasá un `customConverter` si necesitás un parámetro numérico nativo. | +| Operadores de comparación | Solo están mapeados `GreaterThan`, `GreaterThanOrEqualTo`, `LessThan`, `LessThanOrEqualTo`. Cualquier otro `ComparisonOp` lanza `NotSupportedException`. | +| Cobertura de `LikeOp` | Solo están mapeados `Contains`, `StartsWith`, `EndsWith`. Cualquier otro `LikeOp` lanza `NotSupportedException`. | + +--- + +## Ejemplo completo + +Un filtro realista que combina igualdad, rango, membresía y verificaciones de nulos, ejecutado contra un cluster real de Couchbase con el SDK oficial: + +```csharp +using Couchbase; +using Couchbase.Query; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Couchbase.Extensions; +using Vali_Flow.NoSql.Couchbase.Models; + +var cluster = await Cluster.ConnectAsync( + "couchbase://localhost", + "Administrator", + "password"); + +// Construir el filtro +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Processing") + .GreaterThanOrEqualTo(x => x.Total, 100m) + .LessThan(x => x.Total, 5000m) + .In(x => x.RegionCode, new[] { "US", "CA", "MX" }) + .IsNotNull(x => x.CustomerId); + +CouchbaseFilterExpression f = filter.ToCouchbase(); + +// f.WhereClause: +// "(((`Status` = $p0 AND (`Total` >= $p1 AND (`Total` < $p2 AND (`RegionCode` IN $p3 AND `CustomerId` IS NOT NULL)))))" + +var query = $"SELECT META(o).id, o.* FROM `orders` o WHERE {f.WhereClause}"; + +var options = new QueryOptions(); +foreach (var (name, value) in f.Parameters) + options.Parameter(name, value); + +// NOTA: QueryOptions.Parameter(string, object) es la API de enlace de parámetros +// con nombre del SDK CouchbaseNetClient en la línea 3.x del SDK .NET de Couchbase. +// Verificá la sobrecarga exacta contra la versión del SDK que referencies — algunas +// versiones exponen en cambio un setter de NamedParameters basado en JObject. +IQueryResult result = await cluster.QueryAsync(query, options); + +await foreach (var order in result) +{ + Console.WriteLine(order.Status); +} +``` + +### Manejando un `decimal` nativo con un conversor personalizado + +```csharp +// Por defecto los decimales se enlazan como strings (ver Mapeo de tipos). Sobreescribí +// cuando el esquema del bucket almacena Total como número N1QL nativo. +var filter = new ValiFlow() + .GreaterThan(x => x.Total, 100m); + +CouchbaseFilterExpression f = filter.ToCouchbase(value => value is decimal d ? (object)d : null); + +var query = $"SELECT * FROM `orders` WHERE {f.WhereClause}"; +var options = new QueryOptions(); +foreach (var (name, value) in f.Parameters) + options.Parameter(name, value); + +IQueryResult result = await cluster.QueryAsync(query, options); +``` diff --git a/docs/es/vali-flow-nosql-firestore.md b/docs/es/vali-flow-nosql-firestore.md new file mode 100644 index 0000000..e8257ab --- /dev/null +++ b/docs/es/vali-flow-nosql-firestore.md @@ -0,0 +1,234 @@ +# Vali-Flow.NoSql.Firestore — Referencia Completa + +## Tabla de Contenidos + +1. [Resumen](#resumen) +2. [Instalación](#instalación) +3. [Inicio Rápido](#inicio-rápido) +4. [Métodos de Extensión](#métodos-de-extensión) +5. [Operaciones Soportadas](#operaciones-soportadas) +6. [Mapeo de Tipos](#mapeo-de-tipos) +7. [Conversor de Valores Personalizado](#conversor-de-valores-personalizado) +8. [Limitaciones](#limitaciones) +9. [Ejemplo Completo](#ejemplo-completo) + +--- + +## Resumen + +**Vali-Flow.NoSql.Firestore** traduce un árbol de expresiones `ValiFlow` a un `Google.Cloud.Firestore.Filter` nativo. A diferencia de los adaptadores SQL/MongoDB, este paquete no construye un documento ni un string — produce el objeto `Filter` real del SDK oficial `Google.Cloud.Firestore` (v4.4.0), así que el resultado se pasa directo a `Query.Where(filter)` / `CollectionReference.Where(filter)` sin ningún cast, wrapping ni paso de serialización. + +Como el adaptador está atado al tipo real del SDK, hereda tanto las capacidades reales del SDK como sus huecos reales. El motor de queries de Firestore es intencionalmente limitado comparado con una base de datos de propósito general: no hay operador de pattern-matching y no hay forma de negar un sub-filtro arbitrario. Ambas limitaciones están forzadas en el código (ver [Limitaciones](#limitaciones)) en vez de producir silenciosamente un filtro incorrecto. + +--- + +## Instalación + +```bash +dotnet add package Vali-Flow.NoSql.Firestore +``` + +`Vali-Flow.NoSql` (la capa de IR) se incluye como dependencia transitiva. `Google.Cloud.Firestore` 4.4.0 es una dependencia directa — este paquete no intenta abstraerlo. + +--- + +## Inicio Rápido + +```csharp +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Firestore.Extensions; +using Google.Cloud.Firestore; + +var filter = new ValiFlow() + .EqualTo(x => x.IsActive, true) + .GreaterThan(x => x.Age, 18); + +Filter firestoreFilter = filter.ToFirestore(); + +FirestoreDb firestoreDb = FirestoreDb.Create("my-project-id"); +CollectionReference collection = firestoreDb.Collection("users"); +Query query = collection.Where(firestoreFilter); +QuerySnapshot snapshot = await query.GetSnapshotAsync(); + +foreach (DocumentSnapshot doc in snapshot.Documents) +{ + var user = doc.ConvertTo(); +} +``` + +--- + +## Métodos de Extensión + +Ambas sobrecargas viven en `Vali_Flow.NoSql.Firestore.Extensions.ValiFlowFirestoreExtensions`. + +### `ToFirestore(this ValiFlow flow, Func? customConverter = null)` + +Traduce las condiciones acumuladas en un builder `ValiFlow` a un `Filter` nativo. + +| Parámetro | Tipo | Requerido | Descripción | +|-----------|------|-----------|--------------| +| `flow` | `ValiFlow` | Sí | El builder con las condiciones. Lanza `ArgumentNullException` si es `null`. | +| `customConverter` | `Func?` | No | Hook para mapear tipos CLR que el switch incorporado no maneja. Retornar `null` para caer en la conversión por defecto. Está acotado a esta llamada (thread-safe). | + +**Retorna:** `Filter` — pasalo directo a `Query.Where(filter)`. + +### `ToFirestore(this Expression> expression, Func? customConverter = null)` + +Misma traducción para un `Expression>` ya construido. + +```csharp +Expression> expr = o => o.Status == "Pending" && o.Total > 50m; +Filter filter = expr.ToFirestore(); +``` + +Ambas sobrecargas son wrappers delgados sobre `FirestoreFilterTranslator.Translate(IConditionNode, Func?)` — la sobrecarga de `ValiFlow` llama primero a `flow.ToNoSqlIR()`, y la de expresión llama primero a `expression.ToNoSqlIR()`. + +--- + +## Operaciones Soportadas + +| Método ValiFlow | Nodo IR | Llamada a `Filter` de Firestore | +|------------------|---------|-----------------------------------| +| `.EqualTo(x => x.Field, v)` | `EqualNode(IsNegated: false)` | `Filter.EqualTo(field, value)` | +| `.NotEqualTo(x => x.Field, v)` | `EqualNode(IsNegated: true)` | `Filter.NotEqualTo(field, value)` | +| `.GreaterThan(x => x.Field, v)` | `ComparisonNode(GreaterThan)` | `Filter.GreaterThan(field, value)` | +| `.GreaterThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(GreaterThanOrEqual)` | `Filter.GreaterThanOrEqualTo(field, value)` | +| `.LessThan(x => x.Field, v)` | `ComparisonNode(LessThan)` | `Filter.LessThan(field, value)` | +| `.LessThanOrEqualTo(x => x.Field, v)` | `ComparisonNode(LessThanOrEqual)` | `Filter.LessThanOrEqualTo(field, value)` | +| `.In(x => x.Field, list)` | `InNode` | `Filter.InArray(field, values)` | +| `.IsNull(x => x.Field)` | `NullNode(IsNull)` | `Filter.EqualTo(field, null)` | +| `.IsNotNull(x => x.Field)` | `NullNode(IsNotNull)` | `Filter.NotEqualTo(field, null)` | +| `.And(a, b)` | `AndNode` | `Filter.And(left, right)` | +| `.Or(a, b)` | `OrNode` | `Filter.Or(left, right)` | +| `.Contains` / `.StartsWith` / `.EndsWith` | `LikeNode` | **lanza** `NotSupportedException` | +| `.Not(inner)` | `NotNode` | **lanza** `NotSupportedException` | + +`And`/`Or` anidan recursivamente, replicando exactamente la forma del árbol IR — no hay un "flattening" a un único `Filter.And(a, b, c, ...)` aunque la expresión original encadene más de dos condiciones; cada nodo binario se convierte en una llamada anidada `Filter.And`/`Filter.Or`. + +--- + +## Mapeo de Tipos + +El switch incorporado dentro de `FirestoreFilterTranslator` (método `ToValue`) maneja estos tipos CLR antes de pasar el valor a `Filter.*`: + +| Tipo CLR | Valor pasado a `Filter.*` | +|----------|------------------------------| +| `null` | `null` | +| `Enum` | `int` (vía `Convert.ToInt32(e)`) | +| `DateTimeOffset` | `Timestamp.FromDateTimeOffset(dto)` | +| `DateTime` | `Timestamp.FromDateTime(...)` — convertido a UTC primero si `dt.Kind != DateTimeKind.Utc` | +| cualquier otro (`string`, `int`, `long`, `double`, `bool`, `decimal`, ...) | pasa sin cambios — el SDK de Firestore los serializa de forma nativa | + +Orden de resolución: `customConverter` (si se provee) corre primero vía `ConditionValueResolver.Resolve`; si retorna `null`, aplica el switch incorporado de arriba. + +--- + +## Conversor de Valores Personalizado + +Usá `customConverter` para tipos de dominio que el switch incorporado no conoce, o para sobreescribir un default (por ejemplo, almacenar un `decimal` como `double` en vez de dejar que el SDK lo serialice tal cual). + +El conversor corre **antes** del switch incorporado. Retorná `null` para dejar que el default maneje el valor. + +```csharp +// Tipo de dominio +record Money(decimal Amount, string Currency); + +// Conversor: almacenar Money como un double del monto +Filter filter = new ValiFlow() + .GreaterThan(x => x.Price, new Money(100m, "USD")) + .ToFirestore(value => + { + if (value is Money m) + return (double)m.Amount; + return null; // dejar pasar todo lo demás + }); +``` + +--- + +## Limitaciones + +Firestore es el proveedor con más huecos reales en su motor de queries entre los adaptadores NoSql de Vali-Flow, y este paquete **no** lo esconde detrás de un filtro silenciosamente incorrecto — los nodos no soportados lanzan de inmediato al momento de traducir. + +### 1. Sin pattern matching — `LikeNode` (Contains / StartsWith / EndsWith) + +Firestore no tiene operador de query LIKE, regex, ni de substring. Las tres variantes de `LikeNode` lanzan, con el `LikeOp` específico nombrado en el mensaje: + +```csharp +new ValiFlow().Contains(x => x.Name, "ana").ToFirestore(); +// lanza NotSupportedException: +// "Firestore does not support pattern-matching queries (LikeOp.Contains). +// There is no regex/LIKE query operator — filter client-side or use a +// dedicated search index (e.g. Algolia/Elasticsearch) instead." +``` + +Lo mismo pasa con `LikeOp.StartsWith` y `LikeOp.EndsWith` — solo cambia el nombre del operador en el mensaje. **Workaround:** filtrá el resultado del lado del cliente después de obtenerlo, o integrá un índice de búsqueda dedicado (Algolia, Elasticsearch, Typesense) para casos de búsqueda de texto. + +### 2. Sin NOT genérico sobre un sub-árbol arbitrario — `NotNode` + +El SDK de Firestore no expone una composición de "negar este filtro" — no existe un `Filter.Not(filter)`. Cualquier llamada a `.Not(inner)` lanza incondicionalmente, sin importar qué sea `inner`: + +```csharp +new ValiFlow().Not(f => f.EqualTo(x => x.IsActive, true)).ToFirestore(); +// lanza NotSupportedException: +// "Firestore does not support a generic NOT filter over an arbitrary +// sub-expression. The SDK only exposes field-level negations +// (NotEqualTo/NotInArray) via Filter, which are already handled when +// the negated node is an EqualNode/InNode directly." +``` + +**Workaround:** no envuelvas en `.Not(...)`. Expresá la negación a nivel de campo directamente — usá `.NotEqualTo(x => x.Field, v)` (que se convierte en `EqualNode.IsNegated = true` → `Filter.NotEqualTo`), en vez de `.Not(f => f.EqualTo(x => x.Field, v))`. + +### 3. `.In(...)` todavía no tiene contraparte negada + +El SDK expone `Filter.NotInArray(field, values)`, y los comentarios de documentación del traductor lo reconocen — pero `InNode` en el IR actual no tiene un flag `IsNegated` (a diferencia de `EqualNode`), así que por ahora no hay ningún método de `ValiFlow` que llegue a `Filter.NotInArray`. Esto no es una excepción lanzada, simplemente es una operación que todavía no es alcanzable desde la API fluida contra este proveedor. + +### 4. `AND`/`OR` compuestos y anidados mapean 1:1, sin flattening + +No es una funcionalidad faltante, pero vale saberlo: encadenar tres o más condiciones produce un `Filter.And(a, Filter.And(b, c))` anidado en vez de un único `Filter.And(a, b, c)` plano. Firestore acepta filtros compuestos anidados, así que es semánticamente equivalente — solo vale tenerlo presente si inspeccionás el `Filter` generado para debuggear. + +--- + +## Ejemplo Completo + +Un filtro realista que combina igualdad, rango, pertenencia y chequeos de null, ejecutado contra un `FirestoreDb` real: + +```csharp +using Google.Cloud.Firestore; +using Vali_Flow.Core.Builder; +using Vali_Flow.NoSql.Firestore.Extensions; + +// Construir el filtro +var filter = new ValiFlow() + .EqualTo(x => x.Status, "Processing") + .GreaterThanOrEqualTo(x => x.Total, 100m) + .LessThan(x => x.Total, 5000m) + .In(x => x.RegionCode, new[] { "US", "CA", "MX" }) + .IsNotNull(x => x.CustomerId); + +Filter firestoreFilter = filter.ToFirestore(); + +// Ejecutar con el SDK real +FirestoreDb firestoreDb = FirestoreDb.Create("my-project-id"); +CollectionReference collection = firestoreDb.Collection("orders"); +Query query = collection.Where(firestoreFilter).Limit(50); + +QuerySnapshot snapshot = await query.GetSnapshotAsync(); + +foreach (DocumentSnapshot doc in snapshot.Documents) +{ + Order order = doc.ConvertTo(); +} +``` + +### Usando la sobrecarga de expresión + +```csharp +Expression> activeAndAffordable = + p => p.IsActive && p.Price < 200m; + +Filter filter = activeAndAffordable.ToFirestore(); +Query query = firestoreDb.Collection("products").Where(filter); +var snapshot = await query.GetSnapshotAsync(); +``` diff --git a/docs/superpowers/plans/2026-10-06-release-pipeline.md b/docs/superpowers/plans/2026-10-06-release-pipeline.md new file mode 100644 index 0000000..fb65085 --- /dev/null +++ b/docs/superpowers/plans/2026-10-06-release-pipeline.md @@ -0,0 +1,1322 @@ +# Release Pipeline Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Bump all 12 Vali-Flow package versions, revert the 11 temporary `ProjectReference`s back to `PackageReference`, and add `.github/workflows/ci.yml` + `.github/workflows/release.yml` replicating the proven `Vali-Flow.Core`/`Vali-Mediator` pattern extended to this repo's 3-tier dependency chain. + +**Architecture:** Two-stage mechanical prep (version bumps, then reference reverts, in dependency order so nothing ever points at a version that doesn't exist yet) followed by two new workflow files that reuse the exact job shapes already proven in `Vali-Flow.Core`. No application code changes — this plan only touches `.csproj` metadata and adds CI/CD config. + +**Tech Stack:** .NET SDK 9.0.3 (net8.0/net9.0 multi-target), GitHub Actions, `dotnet pack`/`dotnet nuget push`, Python 3 (inline, for the coverage-merge and package-verification scripts — same tool the reference pattern already uses). + +**Spec:** `docs/superpowers/specs/2026-10-06-release-pipeline-design.md` + +## Global Constraints + +- Coverage gate: **95% line coverage per package**, enforced by `ci.yml`'s `coverage` job. Starting gate, not an audited baseline for the 10 packages not measured this session. +- Every package must multi-target `net8.0;net9.0` (already true for all 12 — do not change `TargetFrameworks`). +- No breaking changes in this plan — every version bump is **minor** (new/changed major version is out of scope; if a task's diff looks breaking, stop and flag it instead of bumping differently). +- Never create the GitHub `nuget` environment or its `NUGET_API_KEY` secret — that's the user's manual prerequisite, out of scope for every task below. +- Every `.csproj` edit must preserve the file's existing indentation style (some use 4 spaces, some use 2 — match whatever the file already uses, don't reformat the whole file). +- No task in this plan runs `git push`, triggers the real GitHub Actions workflow, or runs `dotnet nuget push` — this plan stops at a local, verified dry run. + +--- + +### Task 1: Bump `Vali-Flow.Abstractions` to 1.2.0 (wave 1) + +**Files:** +- Modify: `Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj` + +**Interfaces:** +- Consumes: nothing from other tasks. +- Produces: `Vali-Flow.Abstractions` version `1.2.0`, which Tasks 2 and 4 depend on by exact string. + +- [ ] **Step 1: Confirm the current state before editing** + +Run: `grep -n "" "Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj"` +Expected output: `17: 1.1.0` + +- [ ] **Step 2: Bump the version and add a release note** + +In `Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj`, replace: + +```xml + 1.1.0 +``` + +with: + +```xml + 1.2.0 +``` + +And replace: + +```xml + v1.1.0 — Enhanced documentation and internal contracts alignment with ecosystem refactor. +``` + +with: + +```xml + v1.2.0 — Add ValiFlowDiagnostics: a shared ActivitySource-based observability helper (StartActivity/RecordException) used across every Vali-Flow package for Activity-based tracing. No breaking changes. + +v1.1.0 — Enhanced documentation and internal contracts alignment with ecosystem refactor. +``` + +- [ ] **Step 3: Verify the package builds and packs at the new version** + +Run: `dotnet pack Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj --configuration Release -o /tmp/pack-check` +Expected: `Compilación correcta` (or `Build succeeded`), and `/tmp/pack-check/Vali-Flow.Abstractions.1.2.0.nupkg` exists. + +Run: `ls /tmp/pack-check/Vali-Flow.Abstractions.1.2.0.nupkg` +Expected: the file is listed (no "No such file" error). + +- [ ] **Step 4: Commit** + +```bash +git add Vali-Flow.Abstractions/Vali-Flow.Abstractions.csproj +git commit -m "chore(abstractions): bump version to 1.2.0 for release" +``` + +--- + +### Task 2: Bump and re-point the 4 wave-2 packages (`Vali-Flow`, `Vali-Flow.InMemory`, `Vali-Flow.Sql`, `Vali-Flow.NoSql`) + +**Files:** +- Modify: `Vali-Flow/Vali-Flow.csproj` +- Modify: `Vali-Flow.InMemory/Vali-Flow.InMemory.csproj` +- Modify: `Vali-Flow.Sql/Vali-Flow.Sql.csproj` +- Modify: `Vali-Flow.NoSql/Vali-Flow.NoSql.csproj` + +**Interfaces:** +- Consumes: `Vali-Flow.Abstractions` version `1.2.0` (from Task 1) — every file below must pin exactly this string in its `PackageReference`. +- Produces: `Vali-Flow` 1.4.0, `Vali-Flow.InMemory` 1.2.0, `Vali-Flow.Sql` 1.2.0, `Vali-Flow.NoSql` 1.1.1 — `Vali-Flow.NoSql`'s version is consumed by Task 3. + +Each of the 4 files gets the same two changes: (a) swap the `ProjectReference` to `Vali-Flow.Abstractions` back to a `PackageReference` pinned at `1.2.0`, (b) bump its own `` + add a release note. Do all 4 in this one task since they share the same dependency edge and are meaningless to test independently (none of them compile standalone against the old `Vali-Flow.Abstractions` NuGet package — that package doesn't have `ValiFlowDiagnostics` yet, which is exactly why this task exists). + +- [ ] **Step 1: `Vali-Flow/Vali-Flow.csproj` — re-point to PackageReference and bump version** + +Replace: + +```xml + 1.3.4 +``` + +with: + +```xml + 1.4.0 +``` + +Replace: + +```xml + v1.3.4 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. +``` + +with: + +```xml + v1.4.0 — Add GenericRepository<T,TKey> (GetById/GetAll/GetPaged/Add/Update/Delete/SaveChanges, wraps ValiFlowEvaluator<T>). Instrument read/write evaluator methods with ValiFlowDiagnostics Activity tracing. Fix UpsertRangeAsync duplicate-key bug and a PK-overwrite bug in upsert-by-business-key scenarios. Serialize concurrent BulkInsertOrUpdateAsync/BulkUpdateAsync calls per entity type with a generic transient-failure retry (SQL Server/PostgreSQL/MySQL/SQLite). No breaking changes. + +v1.3.4 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. +``` + +Replace: + +```xml + + + + + + +``` + +with: + +```xml + + + +``` + +- [ ] **Step 2: `Vali-Flow.InMemory/Vali-Flow.InMemory.csproj` — re-point to PackageReference and bump version** + +Replace: + +```xml + 1.1.5 +``` + +with: + +```xml + 1.2.0 +``` + +Replace: + +```xml + v1.1.5 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. +``` + +with: + +```xml + v1.2.0 — Fix Update(entity, externalList) leaking into the internal store on a later bare SaveChanges() call. Split ValiFlowEvaluator<T,TProperty> into partial files (Bridge/Read/Write/Grouped). Add an optional tag parameter across read/write/grouped methods, wired to ValiFlowDiagnostics Activity tracing. No breaking changes. + +v1.1.5 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 3: `Vali-Flow.Sql/Vali-Flow.Sql.csproj` — re-point to PackageReference and bump version** + +Replace: + +```xml + 1.1.1 +``` + +with: + +```xml + 1.2.0 +``` + +Replace: + +```xml + v1.1.1 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. +``` + +with: + +```xml + v1.2.0 — Add SqlIdentifierGuard (regex whitelist validation for table/schema/type names) to every builder, fixing a SQL injection vector. Add SetAllFrom(entity, exclude...) reflection-based bulk column mapper to Insert/Update builders. Fix OrIgnore/OrReplace dialect guard, Set()-after-SelectFrom() silent data loss, and Where()-called-twice silent overwrite bugs. Instrument all 6 builders' Build() with ValiFlowDiagnostics Activity tracing. No breaking changes. + +v1.1.1 — Updated Vali-Flow.Core dependency to 2.0.2 (fixes IsNull/NotNull WHERE 0=1 bug with EF Core GlobalQueryFilter). No API changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 4: `Vali-Flow.NoSql/Vali-Flow.NoSql.csproj` — re-point to PackageReference and bump version** + +Replace: + +```xml + 1.1.0 +``` + +with: + +```xml + 1.1.1 +``` + +Replace: + +```xml + v1.1.0 — Enhanced documentation and contracts alignment, improved adapter integration pattern. +``` + +with: + +```xml + v1.1.1 — Fix: x.Field == nullVariable (a closure-captured null) now translates to NullNode like the x.Field == null literal path instead of throwing ArgumentNullException. No breaking changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 5: Verify all 4 packages build and pack against the real `Vali-Flow.Abstractions` 1.2.0 NuGet package** + +This is the real test of this task: these 4 `.csproj` now declare a `PackageReference` to `Vali-Flow.Abstractions` `1.2.0`, but that version is **not yet on NuGet.org** (Task 1 only packed it locally, it was never pushed — this plan never pushes). `dotnet restore`/`dotnet pack` will fail to resolve that package unless it's available from a local source. Add the local pack output from Task 1 as a NuGet source for this verification only: + +Run: `dotnet nuget add source /tmp/pack-check --name local-verify-only 2>&1 || true` +(The `|| true` tolerates "source already exists" if this step is re-run.) + +Run: `dotnet pack Vali-Flow/Vali-Flow.csproj --configuration Release -o /tmp/pack-check` +Expected: `Compilación correcta`, `/tmp/pack-check/Vali-Flow.1.4.0.nupkg` exists. + +Run: `dotnet pack Vali-Flow.InMemory/Vali-Flow.InMemory.csproj --configuration Release -o /tmp/pack-check` +Expected: `Compilación correcta`, `/tmp/pack-check/Vali-Flow.InMemory.1.2.0.nupkg` exists. + +Run: `dotnet pack Vali-Flow.Sql/Vali-Flow.Sql.csproj --configuration Release -o /tmp/pack-check` +Expected: `Compilación correcta`, `/tmp/pack-check/Vali-Flow.Sql.1.2.0.nupkg` exists. + +Run: `dotnet pack Vali-Flow.NoSql/Vali-Flow.NoSql.csproj --configuration Release -o /tmp/pack-check` +Expected: `Compilación correcta`, `/tmp/pack-check/Vali-Flow.NoSql.1.1.1.nupkg` exists. + +Run: `dotnet nuget remove source local-verify-only` +(Cleanup — this local source must not linger in the machine's global NuGet config after this task.) + +- [ ] **Step 6: Commit** + +```bash +git add Vali-Flow/Vali-Flow.csproj Vali-Flow.InMemory/Vali-Flow.InMemory.csproj Vali-Flow.Sql/Vali-Flow.Sql.csproj Vali-Flow.NoSql/Vali-Flow.NoSql.csproj +git commit -m "chore(wave-2): bump versions and re-point Vali-Flow.Abstractions to PackageReference 1.2.0" +``` + +--- + +### Task 3: Bump and re-point the 7 wave-3 NoSQL provider packages + +**Files:** +- Modify: `Vali-Flow.NoSql.MongoDB/Vali-Flow.NoSql.MongoDB.csproj` +- Modify: `Vali-Flow.NoSql.Elasticsearch/Vali-Flow.NoSql.Elasticsearch.csproj` +- Modify: `Vali-Flow.NoSql.Redis/Vali-Flow.NoSql.Redis.csproj` +- Modify: `Vali-Flow.NoSql.DynamoDB/Vali-Flow.NoSql.DynamoDB.csproj` +- Modify: `Vali-Flow.NoSql.Couchbase/Vali-Flow.NoSql.Couchbase.csproj` +- Modify: `Vali-Flow.NoSql.CosmosDb/Vali-Flow.NoSql.CosmosDb.csproj` +- Modify: `Vali-Flow.NoSql.Firestore/Vali-Flow.NoSql.Firestore.csproj` + +**Interfaces:** +- Consumes: `Vali-Flow.NoSql` version `1.1.1` (from Task 2) — every file below must pin exactly this string. +- Produces: 7 packages ready for wave 3 of `release.yml` (Task 5). + +- [ ] **Step 1: `Vali-Flow.NoSql.MongoDB` — bump version and re-point** + +Replace: + +```xml + 1.1.0 +``` + +with: + +```xml + 1.2.0 +``` + +Replace: + +```xml + v1.1.0 — Enhanced documentation and adapter integration pattern alignment. +``` + +with: + +```xml + v1.2.0 — Add a MaxInValues cap (10,000) to InNode translation, a conservative estimate to avoid unbounded $in clauses. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing (tag + entityType). No breaking changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 2: `Vali-Flow.NoSql.Elasticsearch` — bump version and re-point** + +Replace: + +```xml + 1.1.0 +``` + +with: + +```xml + 1.2.0 +``` + +Replace: + +```xml + v1.1.0 — Enhanced documentation and adapter integration pattern alignment. +``` + +with: + +```xml + v1.2.0 — Fix a swallowed inner exception in ToDouble (now wrapped with context instead of lost). Add a MaxInValues cap (65,536, matching index.max_terms_count). Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 3: `Vali-Flow.NoSql.Redis` — bump version and re-point** + +Replace: + +```xml + 1.1.0 +``` + +with: + +```xml + 1.2.0 +``` + +Replace: + +```xml + v1.1.0 — Enhanced documentation and adapter integration pattern alignment. +``` + +with: + +```xml + v1.2.0 — Security fix: escape RediSearch query-syntax special characters in LIKE patterns before adding wildcards, closing a query-injection vector (e.g. a pattern containing ')' or '|' could previously break out of the field's scope). Fix customConverter not being applied in VisitComparison/numeric VisitIn. Add a MaxInValues cap (1,000). Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 4: `Vali-Flow.NoSql.DynamoDB` — bump version and re-point** + +Replace: + +```xml + 1.1.0 +``` + +with: + +```xml + 1.2.0 +``` + +Replace: + +```xml + v1.1.0 — Enhanced documentation and adapter integration pattern alignment. +``` + +with: + +```xml + v1.2.0 — Add a MaxInValues cap. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing (tag + entityType). No breaking changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 5: `Vali-Flow.NoSql.Couchbase` — bump version and re-point** + +Replace: + +```xml + 1.0.0 +``` + +with: + +```xml + 1.1.0 +``` + +Replace: + +```xml + v1.0.0 — Initial release. N1QL (SQL++) WHERE clause translator. +``` + +with: + +```xml + v1.1.0 — Fix: decimal values were bound as N1QL string parameters instead of native numbers, making every comparison operator (=, <>, >, >=, <, <=) against a decimal field silently match zero rows (N1QL does not coerce between string and number). Add a MaxInValues cap. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. +``` + +Replace: + +```xml + + + + + + + +``` + +with: + +```xml + + + + +``` + +- [ ] **Step 6: `Vali-Flow.NoSql.CosmosDb` — bump version and re-point** + +Replace: + +```xml + 1.0.0 +``` + +with: + +```xml + 1.1.0 +``` + +Replace: + +```xml + v1.0.0 — Initial release. Cosmos DB SQL API WHERE clause translator. +``` + +with: + +```xml + v1.1.0 — Add a MaxInValues cap. Instrument Translate(...) with ValiFlowDiagnostics Activity tracing. No breaking changes. +``` + +Replace: + +```xml + + + + + + + +``` + +with: + +```xml + + + + +``` + +- [ ] **Step 7: `Vali-Flow.NoSql.Firestore` — bump version and re-point** + +Replace: + +```xml + 1.0.0 +``` + +with: + +```xml + 1.1.0 +``` + +Replace: + +```xml + v1.0.0 — Initial release. Firestore native Filter translator. +``` + +with: + +```xml + v1.1.0 — Instrument Translate(...) with ValiFlowDiagnostics Activity tracing (tag + entityType). No breaking changes. +``` + +Replace: + +```xml + + + + + + + + +``` + +with: + +```xml + + + + + +``` + +- [ ] **Step 8: Verify all 7 providers build and pack against the real `Vali-Flow.NoSql` 1.1.1 NuGet package** + +Same technique as Task 2 Step 5 — these 7 `.csproj` now reference `Vali-Flow.NoSql` `1.1.1`, which isn't on NuGet.org yet; point `dotnet` at the local pack output. + +Run: `dotnet nuget add source /tmp/pack-check --name local-verify-only 2>&1 || true` + +Run each of the following and expect `Compilación correcta` plus the named `.nupkg` present in `/tmp/pack-check`: + +```bash +dotnet pack Vali-Flow.NoSql.MongoDB/Vali-Flow.NoSql.MongoDB.csproj --configuration Release -o /tmp/pack-check +dotnet pack Vali-Flow.NoSql.Elasticsearch/Vali-Flow.NoSql.Elasticsearch.csproj --configuration Release -o /tmp/pack-check +dotnet pack Vali-Flow.NoSql.Redis/Vali-Flow.NoSql.Redis.csproj --configuration Release -o /tmp/pack-check +dotnet pack Vali-Flow.NoSql.DynamoDB/Vali-Flow.NoSql.DynamoDB.csproj --configuration Release -o /tmp/pack-check +dotnet pack Vali-Flow.NoSql.Couchbase/Vali-Flow.NoSql.Couchbase.csproj --configuration Release -o /tmp/pack-check +dotnet pack Vali-Flow.NoSql.CosmosDb/Vali-Flow.NoSql.CosmosDb.csproj --configuration Release -o /tmp/pack-check +dotnet pack Vali-Flow.NoSql.Firestore/Vali-Flow.NoSql.Firestore.csproj --configuration Release -o /tmp/pack-check +``` + +Expected `.nupkg` files: `Vali-Flow.NoSql.MongoDB.1.2.0.nupkg`, `Vali-Flow.NoSql.Elasticsearch.1.2.0.nupkg`, `Vali-Flow.NoSql.Redis.1.2.0.nupkg`, `Vali-Flow.NoSql.DynamoDB.1.2.0.nupkg`, `Vali-Flow.NoSql.Couchbase.1.1.0.nupkg`, `Vali-Flow.NoSql.CosmosDb.1.1.0.nupkg`, `Vali-Flow.NoSql.Firestore.1.1.0.nupkg`. + +Run: `dotnet nuget remove source local-verify-only` + +- [ ] **Step 9: Commit** + +```bash +git add Vali-Flow.NoSql.MongoDB/Vali-Flow.NoSql.MongoDB.csproj Vali-Flow.NoSql.Elasticsearch/Vali-Flow.NoSql.Elasticsearch.csproj Vali-Flow.NoSql.Redis/Vali-Flow.NoSql.Redis.csproj Vali-Flow.NoSql.DynamoDB/Vali-Flow.NoSql.DynamoDB.csproj Vali-Flow.NoSql.Couchbase/Vali-Flow.NoSql.Couchbase.csproj Vali-Flow.NoSql.CosmosDb/Vali-Flow.NoSql.CosmosDb.csproj Vali-Flow.NoSql.Firestore/Vali-Flow.NoSql.Firestore.csproj +git commit -m "chore(wave-3): bump versions and re-point Vali-Flow.NoSql to PackageReference 1.1.1 in the 7 NoSQL providers" +``` + +--- + +### Task 4: Create `.github/workflows/ci.yml` + +**Files:** +- Create: `.github/workflows/ci.yml` + +**Interfaces:** +- Consumes: the 11 test project names and 12 package project names (all real paths in this repo, listed below). +- Produces: a `workflow_call`-able workflow with a `version-suffix` input, used by Task 5's `release.yml` as `uses: ./.github/workflows/ci.yml`. + +- [ ] **Step 1: Write `.github/workflows/ci.yml`** + +```yaml +name: CI + +# Pull requests, pushes to main and reuse from release.yml (workflow_call). Single required check +# for branch protection: "CI OK". +on: + pull_request: + push: + branches: [main] + workflow_call: + inputs: + version-suffix: + description: Prerelease label appended to every package version (for example rc.1). Empty packs the versions declared in the csproj files. + type: string + default: '' + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +env: + DOTNET_NOLOGO: true + DOTNET_CLI_TELEMETRY_OPTOUT: true + DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 8.0.x + 9.0.x + + - name: Restore + run: dotnet restore vali-flow.sln + + - name: Build + run: dotnet build vali-flow.sln -c Release --no-restore + + test: + name: test / ${{ matrix.os }} / ${{ matrix.tfm }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest] + tfm: [net8.0, net9.0] + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 8.0.x + 9.0.x + + - name: Environment + shell: bash + run: | + mkdir -p logs + { + echo "### ${{ matrix.os }} / ${{ matrix.tfm }}" + uname -a || true + dotnet --info + } 2>&1 | tee logs/00-environment.log + + - name: Restore + shell: bash + run: | + set -o pipefail + dotnet restore vali-flow.sln 2>&1 | tee logs/01-restore.log + + - name: Build + shell: bash + run: | + set -o pipefail + dotnet build vali-flow.sln -c Release --no-restore -v:minimal -bl:logs/build.binlog 2>&1 | tee logs/02-build.log + + # The 11 test projects, one per package family (Vali-Flow.NoSql.Tests also covers the + # MongoDB translator — there is no separate Vali-Flow.NoSql.MongoDB.Tests project). + - name: Unit tests with coverage on ${{ matrix.tfm }} + shell: bash + run: | + set -o pipefail + status=0 + projects="Vali-Flow.Abstractions.Tests Vali-Flow.Tests Vali-Flow.InMemory.Tests Vali-Flow.Sql.Tests Vali-Flow.NoSql.Tests Vali-Flow.NoSql.Elasticsearch.Tests Vali-Flow.NoSql.Redis.Tests Vali-Flow.NoSql.DynamoDB.Tests Vali-Flow.NoSql.Couchbase.Tests Vali-Flow.NoSql.CosmosDb.Tests Vali-Flow.NoSql.Firestore.Tests" + for project in $projects; do + echo "::group::$project on ${{ matrix.tfm }}" + dotnet test "$project" -c Release --no-build -f "${{ matrix.tfm }}" \ + --logger "console;verbosity=detailed" \ + --logger "trx;LogFileName=$project-${{ matrix.tfm }}.trx" \ + --collect:"XPlat Code Coverage" --results-directory "TestResults/${{ matrix.tfm }}/$project" \ + 2>&1 | tee "logs/03-test-$project.log" || status=1 + echo "::endgroup::" + done + exit $status + + - name: Test totals + if: always() + shell: bash + run: | + python3 - <<'PY' + import glob + import os + import xml.etree.ElementTree as ET + + rows = ["| Project | Total | Passed | Failed | Skipped |", "|---|---:|---:|---:|---:|"] + for path in sorted(glob.glob("TestResults/**/*.trx", recursive=True)): + counters = ET.parse(path).getroot().find(".//{*}Counters") + if counters is None: + continue + name = os.path.basename(path)[:-4] + failed = int(counters.get("failed", 0)) + skipped = int(counters.get("total", 0)) - int(counters.get("executed", 0)) + rows.append(f"| {name} | {counters.get('total')} | {counters.get('passed')} | {failed}{' (!)' if failed else ''} | {skipped} |") + report = "### Tests ${{ matrix.os }} / ${{ matrix.tfm }}\n\n" + "\n".join(rows) + "\n" + print(report) + with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as handle: + handle.write(report + "\n") + PY + + - name: Upload coverage reports + if: always() + uses: actions/upload-artifact@v4 + with: + name: coverage-${{ matrix.os }}-${{ matrix.tfm }} + path: TestResults/**/coverage.cobertura.xml + if-no-files-found: error + retention-days: 7 + + - name: Upload full trace + if: always() + uses: actions/upload-artifact@v4 + with: + name: trace-${{ matrix.os }}-${{ matrix.tfm }} + path: | + logs/** + TestResults/**/*.trx + if-no-files-found: warn + retention-days: 14 + + trace: + name: Full trace (single file) + needs: test + if: always() + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + with: + pattern: trace-* + path: trace + + - name: Merge every log into one file + shell: bash + run: | + out=full-trace.txt + : > "$out" + while IFS= read -r f; do + rel="${f#trace/}" + { + echo + echo "==================================================================" + echo "== ${rel%%/*} :: ${rel#*/}" + echo "==================================================================" + cat "$f" + } >> "$out" + done < <(find trace -name '*.log' | sort) + wc -l "$out" + { + echo "### Full trace" + echo + echo "Download the **full-trace** artifact of this run: one text file with the environment, restore, build and" + echo "detailed test output of every OS x target framework cell." + } >> "$GITHUB_STEP_SUMMARY" + + - name: Upload the single-file trace + uses: actions/upload-artifact@v4 + with: + name: full-trace + path: full-trace.txt + if-no-files-found: error + retention-days: 14 + + coverage: + # NOTE: 95% is a starting gate, not an audited baseline for the 10 packages not measured in the + # session that stood this pipeline up (Vali-Flow itself was: 97.42%). Adjust per-library after + # the first green run shows the real numbers. + name: Coverage gate (>= 95% per library) + needs: test + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + with: + pattern: coverage-* + path: coverage + + - name: Merge reports and enforce the gate + env: + THRESHOLD: '95' + run: | + python3 - <<'PY' + import glob + import os + import sys + import xml.etree.ElementTree as ET + + LIBS = [ + "Vali-Flow.Abstractions", "Vali-Flow", "Vali-Flow.InMemory", "Vali-Flow.Sql", + "Vali-Flow.NoSql", "Vali-Flow.NoSql.MongoDB", "Vali-Flow.NoSql.Elasticsearch", + "Vali-Flow.NoSql.Redis", "Vali-Flow.NoSql.DynamoDB", "Vali-Flow.NoSql.Couchbase", + "Vali-Flow.NoSql.CosmosDb", "Vali-Flow.NoSql.Firestore", + ] + THRESHOLD = float(os.environ["THRESHOLD"]) + OSES = ["ubuntu-latest", "windows-latest"] + TFMS = ["net8.0", "net9.0"] + + missing = [ + f"coverage-{os_name}-{tfm}" + for os_name in OSES + for tfm in TFMS + if not glob.glob(f"coverage/coverage-{os_name}-{tfm}/**/coverage.cobertura.xml", recursive=True) + ] + + lines = {lib: {} for lib in LIBS} + reports = glob.glob("coverage/**/coverage.cobertura.xml", recursive=True) + for path in reports: + for package in ET.parse(path).getroot().iter("package"): + store = lines.get(package.get("name")) + if store is None: + continue + for cls in package.iter("class"): + parts = cls.get("filename").replace("\\", "/").split("/") + file_key = "/".join(parts[-2:]) + for line in cls.iter("line"): + key = (file_key, int(line.get("number"))) + store[key] = max(store.get(key, 0), int(line.get("hits"))) + + rows = ["| Library | Lines | Covered | Line coverage | Gate |", "|---|---:|---:|---:|:---:|"] + failed = [] + for lib in LIBS: + total = len(lines[lib]) + covered = sum(1 for hits in lines[lib].values() if hits > 0) + pct = 100.0 * covered / total if total else 0.0 + ok = total > 0 and pct >= THRESHOLD + if not ok: + failed.append(lib) + rows.append(f"| {lib} | {total} | {covered} | {pct:.1f}% | {'pass' if ok else 'FAIL'} |") + + cells = ", ".join(f"{o} / {t}" for o in OSES for t in TFMS) + report = (f"### Unit-test line coverage (gate >= {THRESHOLD:g}%, {len(reports)} reports merged)\n\n" + + "\n".join(rows) + + f"\n\nExpected cells: {cells}\n" + + (f"\nMissing reports: {', '.join(missing)}\n" if missing else "\nAll 4 OS x TFM reports present.\n")) + print(report) + with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as handle: + handle.write(report + "\n") + if missing: + sys.exit("Coverage gate failed: missing reports for " + ", ".join(missing)) + if failed: + sys.exit("Coverage gate failed for: " + ", ".join(failed)) + PY + + pack: + name: Pack NuGet packages + needs: build + runs-on: ubuntu-latest + env: + VERSION_SUFFIX: ${{ inputs.version-suffix }} + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 8.0.x + 9.0.x + + - name: Apply the prerelease label + if: ${{ inputs.version-suffix != '' }} + run: | + if ! [[ "$VERSION_SUFFIX" =~ ^[0-9A-Za-z.-]+$ ]]; then + echo "::error::version-suffix may only contain letters, digits, dots and hyphens" + exit 1 + fi + cat > Directory.Build.targets <<'XML' + + + $(Version)-$(PrereleaseLabel) + + + XML + + - name: Pack every package in dependency order + run: | + for project in Vali-Flow.Abstractions Vali-Flow Vali-Flow.InMemory Vali-Flow.Sql Vali-Flow.NoSql Vali-Flow.NoSql.MongoDB Vali-Flow.NoSql.Elasticsearch Vali-Flow.NoSql.Redis Vali-Flow.NoSql.DynamoDB Vali-Flow.NoSql.Couchbase Vali-Flow.NoSql.CosmosDb Vali-Flow.NoSql.Firestore; do + dotnet pack "$project/$project.csproj" -c Release -o artifacts ${VERSION_SUFFIX:+-p:PrereleaseLabel="$VERSION_SUFFIX"} + done + + - name: Verify package contents + run: | + python3 - <<'PY' + import glob + import sys + import xml.etree.ElementTree as ET + import zipfile + + PACKAGES = { + "Vali-Flow.Abstractions", "Vali-Flow", "Vali-Flow.InMemory", "Vali-Flow.Sql", + "Vali-Flow.NoSql", "Vali-Flow.NoSql.MongoDB", "Vali-Flow.NoSql.Elasticsearch", + "Vali-Flow.NoSql.Redis", "Vali-Flow.NoSql.DynamoDB", "Vali-Flow.NoSql.Couchbase", + "Vali-Flow.NoSql.CosmosDb", "Vali-Flow.NoSql.Firestore", + } + TFMS = {"net8.0", "net9.0"} + + errors = [] + found = {} + for path in sorted(glob.glob("artifacts/*.nupkg")): + with zipfile.ZipFile(path) as archive: + names = archive.namelist() + root = ET.fromstring(archive.read(next(n for n in names if n.endswith(".nuspec")))) + ns = {"n": root.tag.split("}")[0].strip("{")} + pid = root.find("n:metadata/n:id", ns).text + version = root.find("n:metadata/n:version", ns).text + libs = {n.split("/")[1] for n in names if n.startswith("lib/") and n.endswith(".dll")} + found[pid] = (version, libs) + + for pid in sorted(PACKAGES - set(found)): + errors.append(f"{pid}: package missing from artifacts/") + for pid, (version, libs) in sorted(found.items()): + if libs != TFMS: + errors.append(f"{pid} {version}: lib/ has {sorted(libs)}, expected {sorted(TFMS)}") + print(f"{pid} {version}: lib {sorted(libs)}") + if errors: + sys.exit("Package check failed:\n " + "\n ".join(errors)) + print("Package check passed.") + PY + + - name: Upload packages + uses: actions/upload-artifact@v4 + with: + name: nuget-packages + path: artifacts/* + if-no-files-found: error + retention-days: 14 + + ci-ok: + name: CI OK + if: always() + needs: [build, test, coverage, pack] + runs-on: ubuntu-latest + steps: + - name: Every job must have succeeded + env: + RESULTS: ${{ toJSON(needs.*.result) }} + run: | + echo "$RESULTS" + if echo "$RESULTS" | grep -Eq '"(failure|cancelled|skipped)"'; then + exit 1 + fi +``` + +- [ ] **Step 2: Validate the YAML is syntactically well-formed** + +Run: `python3 -c "import yaml, sys; yaml.safe_load(open('.github/workflows/ci.yml'))" 2>&1 || python3 -c "import json; print('yaml module unavailable, skipping — will be validated by GitHub on first push')"` +Expected: no exception printed (either the yaml module parses it cleanly, or the fallback message prints — either way, no traceback). + +- [ ] **Step 3: Commit** + +```bash +git add .github/workflows/ci.yml +git commit -m "ci: add reusable CI workflow (build, test matrix, 95% coverage gate, pack)" +``` + +--- + +### Task 5: Create `.github/workflows/release.yml` + +**Files:** +- Create: `.github/workflows/release.yml` + +**Interfaces:** +- Consumes: `.github/workflows/ci.yml` (Task 4) via `uses: ./.github/workflows/ci.yml`. +- Produces: the manually-triggered release workflow. Nothing downstream in this plan depends on it — this is the final deliverable. + +- [ ] **Step 1: Write `.github/workflows/release.yml`** + +```yaml +name: Release + +# Manual only. By default it runs the full CI (net8.0/net9.0 on Linux and Windows) and uploads the +# packed NuGet packages as a workflow artifact; it publishes NOTHING. Publishing needs BOTH +# `publish: true` and an approval of the `nuget` environment (Settings > Environments > nuget > +# Required reviewers), and uses the NUGET_API_KEY secret of that environment. +# +# Publication order — 3 waves, because this repo has a 2-level dependency chain on top of the core: +# Wave 1: Vali-Flow.Abstractions alone. +# Wave 2: Vali-Flow, Vali-Flow.InMemory, Vali-Flow.Sql, Vali-Flow.NoSql (all depend on Abstractions). +# Wave 3: the 7 NoSQL provider packages (all depend on Vali-Flow.NoSql from wave 2). +# Each wave waits for NuGet.org to index the package the next wave needs before proceeding. +on: + workflow_dispatch: + inputs: + version-suffix: + description: Prerelease label appended to every package version, for example rc.1 (empty = versions from the csproj files) + type: string + required: false + default: '' + publish: + description: Publish the packages to NuGet.org after the approval of the nuget environment + type: boolean + default: false + +permissions: + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + ci: + name: CI (build, test on net8.0/net9.0, coverage gate, pack) + uses: ./.github/workflows/ci.yml + with: + version-suffix: ${{ inputs.version-suffix }} + + publish: + name: Publish to NuGet (needs approval) + needs: ci + if: ${{ inputs.publish }} + runs-on: ubuntu-latest + environment: nuget + env: + NUGET_SOURCE: https://api.nuget.org/v3/index.json + steps: + - uses: actions/download-artifact@v4 + with: + name: nuget-packages + path: artifacts + + - name: Every package must contain net8.0 and net9.0 + run: | + for package in artifacts/*.nupkg; do + for tfm in net8.0 net9.0; do + unzip -l "$package" | grep -q "lib/$tfm/" || { echo "::error::$package has no lib/$tfm"; exit 1; } + done + done + + - name: Check NUGET_API_KEY is configured + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + if [ -z "$NUGET_API_KEY" ]; then + echo "::error::NUGET_API_KEY is not set in the nuget environment" + exit 1 + fi + + # ---- Wave 1: Vali-Flow.Abstractions alone ---- + - name: 'Wave 1: push Vali-Flow.Abstractions' + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + # Vali-Flow.Abstractions is the only package whose id is followed by a version digit + # among files matching "Vali-Flow.Abstractions.*" (there is no other package with that + # prefix), so a plain glob is unambiguous here. + dotnet nuget push artifacts/Vali-Flow.Abstractions.[0-9]*.nupkg --source "$NUGET_SOURCE" --api-key "$NUGET_API_KEY" --skip-duplicate + + - name: 'Wave 1: wait until NuGet.org lists Vali-Flow.Abstractions' + run: | + pkg=$(basename artifacts/Vali-Flow.Abstractions.[0-9]*.nupkg .nupkg) + version=$(echo "${pkg#Vali-Flow.Abstractions.}" | tr '[:upper:]' '[:lower:]') + for attempt in $(seq 1 40); do + if curl -fsS "https://api.nuget.org/v3-flatcontainer/vali-flow.abstractions/index.json" | grep -q "\"$version\""; then + echo "Vali-Flow.Abstractions $version is indexed" + exit 0 + fi + echo "attempt $attempt/40: Vali-Flow.Abstractions $version not indexed yet" + sleep 30 + done + echo "::error::Vali-Flow.Abstractions $version was not indexed in time; re-run this job (--skip-duplicate makes it safe)" + exit 1 + + # ---- Wave 2: Vali-Flow, Vali-Flow.InMemory, Vali-Flow.Sql, Vali-Flow.NoSql ---- + - name: 'Wave 2: push Vali-Flow, Vali-Flow.InMemory, Vali-Flow.Sql, Vali-Flow.NoSql' + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + # Vali-Flow.[0-9]* matches only the main package (not Vali-Flow.InMemory.*, Vali-Flow.Sql.*, + # or Vali-Flow.NoSql.* — those have a literal "." before a letter, not a digit). + for pattern in 'Vali-Flow.[0-9]*' 'Vali-Flow.InMemory.[0-9]*' 'Vali-Flow.Sql.[0-9]*' 'Vali-Flow.NoSql.[0-9]*'; do + dotnet nuget push "artifacts/$pattern.nupkg" --source "$NUGET_SOURCE" --api-key "$NUGET_API_KEY" --skip-duplicate + done + + - name: 'Wave 2: wait until NuGet.org lists Vali-Flow.NoSql' + run: | + # Only Vali-Flow.NoSql gates wave 3 — the 7 providers depend on it, not on Vali-Flow/InMemory/Sql. + pkg=$(basename artifacts/Vali-Flow.NoSql.[0-9]*.nupkg .nupkg) + version=$(echo "${pkg#Vali-Flow.NoSql.}" | tr '[:upper:]' '[:lower:]') + for attempt in $(seq 1 40); do + if curl -fsS "https://api.nuget.org/v3-flatcontainer/vali-flow.nosql/index.json" | grep -q "\"$version\""; then + echo "Vali-Flow.NoSql $version is indexed" + exit 0 + fi + echo "attempt $attempt/40: Vali-Flow.NoSql $version not indexed yet" + sleep 30 + done + echo "::error::Vali-Flow.NoSql $version was not indexed in time; re-run this job (--skip-duplicate makes it safe)" + exit 1 + + # ---- Wave 3: the 7 NoSQL provider packages ---- + - name: 'Wave 3: push the 7 NoSQL provider packages' + env: + NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }} + run: | + for package in artifacts/Vali-Flow.NoSql.*.nupkg; do + case "$(basename "$package")" in + Vali-Flow.NoSql.[0-9]*) continue ;; # already pushed in wave 2 + esac + dotnet nuget push "$package" --source "$NUGET_SOURCE" --api-key "$NUGET_API_KEY" --skip-duplicate + done +``` + +- [ ] **Step 2: Validate the YAML is syntactically well-formed** + +Run: `python3 -c "import yaml, sys; yaml.safe_load(open('.github/workflows/release.yml'))" 2>&1 || python3 -c "import json; print('yaml module unavailable, skipping — will be validated by GitHub on first push')"` +Expected: no traceback. + +- [ ] **Step 3: Commit** + +```bash +git add .github/workflows/release.yml +git commit -m "ci: add manual release workflow (3-wave dependency-ordered NuGet publish)" +``` + +--- + +### Task 6: Full local dry-run validation + +**Files:** none created or modified — this task only runs commands. + +**Interfaces:** +- Consumes: the final state of all 12 `.csproj` (Tasks 1-3) and both workflow files (Tasks 4-5). +- Produces: a go/no-go signal for whether this repo is actually ready for a real `workflow_dispatch` run. This is the task the plan's "Goal" and "Testing" section in the spec point to. + +- [ ] **Step 1: Full solution build from a clean restore** + +Run: `dotnet restore vali-flow.sln && dotnet build vali-flow.sln --configuration Release --no-restore` +Expected: `0 Errores` / `0 Error(s)`. If this fails with a missing-package error for `Vali-Flow.Abstractions` 1.2.0 or `Vali-Flow.NoSql` 1.1.1, a reference from Tasks 2/3 was left on the old `ProjectReference` or missed the version bump — go back and check `git diff` against Tasks 2/3's exact replacements. + +- [ ] **Step 2: Full test suite** + +Run: `dotnet test vali-flow.sln --configuration Release --no-build` +Expected: every one of the 11 test projects reports `Correctas!` / 0 failures (the exact counts don't matter here — this plan didn't change any production logic, only package metadata and dependency wiring — but a sudden failure means a reference edit broke something and must be investigated before continuing). + +- [ ] **Step 3: Pack all 12 packages at their final bumped versions, with no local-source workaround** + +This step is the real end-to-end check: if Tasks 1-3 are fully consistent, every package now resolves its sibling dependency as a normal transitive `PackageReference`-of-a-`PackageReference` chain once wave 1/2 packages are copied into a local feed — simulate that without ever touching the real NuGet.org: + +```bash +mkdir -p /tmp/local-feed +for project in Vali-Flow.Abstractions Vali-Flow Vali-Flow.InMemory Vali-Flow.Sql Vali-Flow.NoSql Vali-Flow.NoSql.MongoDB Vali-Flow.NoSql.Elasticsearch Vali-Flow.NoSql.Redis Vali-Flow.NoSql.DynamoDB Vali-Flow.NoSql.Couchbase Vali-Flow.NoSql.CosmosDb Vali-Flow.NoSql.Firestore; do + dotnet pack "$project/$project.csproj" --configuration Release -o /tmp/local-feed +done +ls /tmp/local-feed/*.nupkg | wc -l +``` + +Expected: `24` lines from the `ls | wc -l` (12 packages × `.nupkg` + `.snupkg` each — if the count is `12`, symbol packages aren't being produced, which is a packaging regression worth flagging before moving on, not silently accepted). + +Expected version list — run `ls /tmp/local-feed/*.nupkg | sort` and confirm it matches exactly: + +``` +Vali-Flow.1.4.0.nupkg +Vali-Flow.Abstractions.1.2.0.nupkg +Vali-Flow.InMemory.1.2.0.nupkg +Vali-Flow.NoSql.1.1.1.nupkg +Vali-Flow.NoSql.Couchbase.1.1.0.nupkg +Vali-Flow.NoSql.CosmosDb.1.1.0.nupkg +Vali-Flow.NoSql.DynamoDB.1.2.0.nupkg +Vali-Flow.NoSql.Elasticsearch.1.2.0.nupkg +Vali-Flow.NoSql.Firestore.1.1.0.nupkg +Vali-Flow.NoSql.MongoDB.1.2.0.nupkg +Vali-Flow.NoSql.Redis.1.2.0.nupkg +Vali-Flow.Sql.1.2.0.nupkg +``` + +- [ ] **Step 4: Confirm no stray local NuGet source was left behind on this machine** + +Run: `dotnet nuget list source` +Expected: no entry named `local-verify-only` (added and removed in Tasks 2 and 3 — if it's still listed, remove it now with `dotnet nuget remove source local-verify-only`, since leaving a `/tmp` path as a permanent NuGet source would silently break restores on this machine after `/tmp` is cleared). + +- [ ] **Step 5: Report the dry-run result** + +No commit for this task (nothing was created or modified). Summarize in the chat: build result, test result, the 12-package version/pack confirmation, and that `.github/workflows/{ci.yml,release.yml}` exist and are ready for the user to exercise with a real `workflow_dispatch` (`publish: false` first, to validate the GitHub-hosted runners end-to-end before ever approving a real publish) once the `nuget` GitHub environment prerequisite is in place. diff --git a/docs/superpowers/specs/2026-10-06-release-pipeline-design.md b/docs/superpowers/specs/2026-10-06-release-pipeline-design.md new file mode 100644 index 0000000..1d475b6 --- /dev/null +++ b/docs/superpowers/specs/2026-10-06-release-pipeline-design.md @@ -0,0 +1,145 @@ +# Design: Release pipeline for Vali-Flow (GitHub Actions) + +**Date:** 2026-10-06 +**Status:** Approved + +## Problem + +The Vali-Flow repository ships 12 independent NuGet packages with a two-level dependency chain +(`Vali-Flow.Abstractions` → `Vali-Flow`/`Vali-Flow.InMemory`/`Vali-Flow.Sql`/`Vali-Flow.NoSql` → +the 7 NoSQL provider packages), and has **no CI/CD at all** today — no `.github/workflows/` +directory exists. Publishing has been manual. This session's work (observability, bug fixes found +via stress testing, new providers) needs to go out, but every package's committed `` +already equals what's currently live on NuGet.org — nothing can be republished without bumping +versions first, and the dependency chain means publishing out of order will push packages whose +declared `PackageReference` points at a version that isn't live yet. + +Two sibling repositories in the same ecosystem (`Vali-Mediator`, `Vali-Flow.Core`) already solved +this with a `ci.yml` + `release.yml` pair. Vali-Flow's job is to extend that same pattern to a third +dependency wave, not invent a new one. + +## Non-goals + +- This spec does not design the test/coverage CI that will also eventually run on every PR — that + is `ci.yml`'s job, reused here, but a from-scratch CI design is out of scope; it follows the + already-proven shape from `Vali-Flow.Core`. +- This spec does not perform the version bump or revert the 11 `.csproj` files currently on + `ProjectReference` (temporary, for this session's stress testing) back to `PackageReference`. + That is a prerequisite carried out before the pipeline can run, tracked separately. +- No changes to `Vali-Flow.Core` (unchanged this session, already published at the version every + package here pins). + +## Reference pattern (what we're extending) + +`Vali-Flow.Core/.github/workflows/{ci.yml,release.yml}` and `Vali-Mediator`'s equivalent files +already implement, for a **two-wave** dependency chain (core, then everything else): + +- `ci.yml`: `workflow_call`-able. Jobs: `build` → `test` (matrix `{ubuntu-latest, windows-latest} × + {net8.0, net9.0}`, coverage collected via `--collect:"XPlat Code Coverage"`) → `coverage` (merges + Cobertura reports across every OS/TFM cell, per-library gate) → `pack` (applies an optional + prerelease suffix, packs every project, verifies every `.nupkg` contains both TFMs) → `ci-ok` + (single required status check). +- `release.yml`: `workflow_dispatch` only, inputs `version-suffix` (optional prerelease label) and + `publish` (boolean, default false). Calls `ci.yml`. If `publish` is true, a second job + (`environment: nuget`, gated on GitHub's environment-approval + required reviewers) downloads the + packed artifact, pushes the core package, polls `https://api.nuget.org/v3-flatcontainer//index.json` + every 30s (up to 40 attempts) until the core version is indexed, then pushes every dependent + package. `--skip-duplicate` on every push makes a re-run safe. + +Vali-Flow reuses this shape unchanged except for the publish job, which needs a third wave. + +## Design + +### 1. `ci.yml` (new, reusable) + +Same shape as `Vali-Flow.Core`'s: `build` (restore + build the whole `.sln`) → `test` (matrix +`{ubuntu-latest, windows-latest} × {net8.0, net9.0}`, runs all 11 test projects, collects per-cell +Cobertura coverage, uploads a `.trx`-based summary table and a merged full-trace artifact) → +`coverage` (merges Cobertura across all 4 cells per library, **95% line-coverage gate per +package** — the 12 packages below are "Library" rows the Python merge script checks by name) → +`pack` (packs all 12 projects with the optional `version-suffix` prerelease label applied via the +same `Directory.Build.targets` injection trick as `Vali-Flow.Core`, verifies every `.nupkg` has +both `lib/net8.0` and `lib/net9.0`) → `ci-ok`. + +**Coverage libraries list** (mirrors `Vali-Flow.Core`'s `LIBS` array, one row per package): +`Vali-Flow.Abstractions`, `Vali-Flow`, `Vali-Flow.InMemory`, `Vali-Flow.Sql`, `Vali-Flow.NoSql`, +`Vali-Flow.NoSql.MongoDB`, `Vali-Flow.NoSql.Elasticsearch`, `Vali-Flow.NoSql.Redis`, +`Vali-Flow.NoSql.DynamoDB`, `Vali-Flow.NoSql.Couchbase`, `Vali-Flow.NoSql.CosmosDb`, +`Vali-Flow.NoSql.Firestore`. `Vali-Flow.Benchmarks` is excluded (no tests, it's a BenchmarkDotNet +project). + +**Threshold note** (same framing as `Vali-Flow.Core`'s own comment): 95% is a starting gate, not an +audited baseline for the 10 packages that weren't measured this session (`Vali-Flow` itself was: +97.42%). The first real CI run will show every package's actual number; any package under 95% needs +either more tests or an explicitly-justified threshold adjustment at that point — not a silent +pre-emptive lowering now. + +### 2. `release.yml` (new) + +Identical `workflow_dispatch` inputs and `ci` job as the reference pattern. The `publish` job +(same `environment: nuget`, same `NUGET_API_KEY` secret, same `--skip-duplicate` everywhere) grows +from 2 steps-with-a-wait to **3 waves**: + +``` +Wave 1: push Vali-Flow.Abstractions..nupkg + wait until nuget.org indexes vali-flow.abstractions/ + +Wave 2: push Vali-Flow..nupkg, Vali-Flow.InMemory..nupkg, + Vali-Flow.Sql..nupkg, Vali-Flow.NoSql..nupkg + wait until nuget.org indexes vali-flow.nosql/ + (Vali-Flow/InMemory/Sql don't gate wave 3 — only NoSql does, since only the + 7 providers in wave 3 depend on it) + +Wave 3: push the 7 Vali-Flow.NoSql.{MongoDB,Elasticsearch,Redis,DynamoDB,Couchbase,CosmosDb,Firestore} + ..nupkg packages +``` + +Each wave's push step globs its packages by filename prefix, same technique the reference pattern +uses to distinguish the core from everything else (e.g. `Vali-Flow.[0-9]*.nupkg` matches only the +main package, not `Vali-Flow.InMemory.*` or `Vali-Flow.Sql.*`, because of the literal dot before the +version digit). The indexed-version check script is parameterized by package id instead of +hardcoded, since there are now two intermediate gates instead of one. + +### 3. Operational prerequisites (not part of this pipeline's code, but required before first use) + +- **GitHub environment `nuget`** must exist on this repo (Settings → Environments) with a + `NUGET_API_KEY` secret and required reviewers configured — identical setup to `Vali-Mediator`/ + `Vali-Flow.Core`. The user sets this up; the pipeline cannot create its own secrets or approval + gates. +- **Version bump + reference cleanup**: every package's `` must be bumped past what's + already live (table below) and the 11 `.csproj` files currently on a temporary `ProjectReference` + (from this session's stress testing) must be reverted to `PackageReference` pinned at the new + version numbers, before any release run — otherwise `pack` either fails to resolve the reference + or ships a package that depends on a version not yet on NuGet. + + | Package | Published (= current csproj) | → New version | + |---|---|---| + | Vali-Flow.Abstractions | 1.1.0 | 1.2.0 | + | Vali-Flow.NoSql | 1.1.0 | 1.1.1 | + | Vali-Flow | 1.3.4 | 1.4.0 | + | Vali-Flow.InMemory | 1.1.5 | 1.2.0 | + | Vali-Flow.Sql | 1.1.1 | 1.2.0 | + | Vali-Flow.NoSql.MongoDB | 1.1.0 | 1.2.0 | + | Vali-Flow.NoSql.Elasticsearch | 1.1.0 | 1.2.0 | + | Vali-Flow.NoSql.Redis | 1.1.0 | 1.2.0 | + | Vali-Flow.NoSql.DynamoDB | 1.1.0 | 1.2.0 | + | Vali-Flow.NoSql.Couchbase | 1.0.0 | 1.1.0 | + | Vali-Flow.NoSql.CosmosDb | 1.0.0 | 1.1.0 | + | Vali-Flow.NoSql.Firestore | 1.0.0 | 1.1.0 | + + All bumps are minor (additive API surface / non-breaking fixes only — no package introduced a + breaking change this session). + +## Testing + +The pipeline's own correctness is validated by running it: a `publish: false` dry run exercises +`build`/`test`/`coverage`/`pack` without touching NuGet, which is the safe way to validate the +workflow YAML and the coverage/pack scripts before ever approving a real publish. The first real +`publish: true` run is the actual end-to-end test of the 3-wave ordering and indexing waits. + +## Error handling + +Same as the reference pattern: `--skip-duplicate` on every `dotnet nuget push` makes any step safe +to re-run after a transient failure (e.g. the indexing wait timing out at 40×30s) without +double-publishing. The `coverage` and `pack` verification steps fail the whole run before anything +is ever pushed, so a broken package can't reach NuGet even on a rushed manual dispatch. diff --git a/vali-flow.sln b/vali-flow.sln index 8f65f8f..5468c40 100644 --- a/vali-flow.sln +++ b/vali-flow.sln @@ -34,6 +34,20 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.DynamoDB", EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.DynamoDB.Tests", "Vali-Flow.NoSql.DynamoDB.Tests\Vali-Flow.NoSql.DynamoDB.Tests.csproj", "{829C5A5A-360C-4CA4-994E-5392ADD76B5E}" EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.Abstractions.Tests", "Vali-Flow.Abstractions.Tests\Vali-Flow.Abstractions.Tests.csproj", "{E7866C39-4CB1-40CE-B243-77B6625C27CB}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.Couchbase", "Vali-Flow.NoSql.Couchbase\Vali-Flow.NoSql.Couchbase.csproj", "{DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.Couchbase.Tests", "Vali-Flow.NoSql.Couchbase.Tests\Vali-Flow.NoSql.Couchbase.Tests.csproj", "{3120575A-19FC-4615-B46F-2220250D3F6C}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.CosmosDb", "Vali-Flow.NoSql.CosmosDb\Vali-Flow.NoSql.CosmosDb.csproj", "{934F750B-9A32-461C-8408-515434A645FF}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.CosmosDb.Tests", "Vali-Flow.NoSql.CosmosDb.Tests\Vali-Flow.NoSql.CosmosDb.Tests.csproj", "{BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.Firestore", "Vali-Flow.NoSql.Firestore\Vali-Flow.NoSql.Firestore.csproj", "{178A6DDD-0448-4D1D-A794-19BA8E8C55AD}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vali-Flow.NoSql.Firestore.Tests", "Vali-Flow.NoSql.Firestore.Tests\Vali-Flow.NoSql.Firestore.Tests.csproj", "{C4C04C75-3BF1-465A-B73E-8099203FFB65}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -248,6 +262,90 @@ Global {829C5A5A-360C-4CA4-994E-5392ADD76B5E}.Release|x64.Build.0 = Release|Any CPU {829C5A5A-360C-4CA4-994E-5392ADD76B5E}.Release|x86.ActiveCfg = Release|Any CPU {829C5A5A-360C-4CA4-994E-5392ADD76B5E}.Release|x86.Build.0 = Release|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Debug|Any CPU.Build.0 = Debug|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Debug|x64.ActiveCfg = Debug|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Debug|x64.Build.0 = Debug|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Debug|x86.ActiveCfg = Debug|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Debug|x86.Build.0 = Debug|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Release|Any CPU.ActiveCfg = Release|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Release|Any CPU.Build.0 = Release|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Release|x64.ActiveCfg = Release|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Release|x64.Build.0 = Release|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Release|x86.ActiveCfg = Release|Any CPU + {E7866C39-4CB1-40CE-B243-77B6625C27CB}.Release|x86.Build.0 = Release|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Debug|Any CPU.Build.0 = Debug|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Debug|x64.ActiveCfg = Debug|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Debug|x64.Build.0 = Debug|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Debug|x86.ActiveCfg = Debug|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Debug|x86.Build.0 = Debug|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Release|Any CPU.ActiveCfg = Release|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Release|Any CPU.Build.0 = Release|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Release|x64.ActiveCfg = Release|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Release|x64.Build.0 = Release|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Release|x86.ActiveCfg = Release|Any CPU + {DBD0AF51-D654-46E1-AA97-AD1E4AAA7E1D}.Release|x86.Build.0 = Release|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Debug|Any CPU.Build.0 = Debug|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Debug|x64.ActiveCfg = Debug|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Debug|x64.Build.0 = Debug|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Debug|x86.ActiveCfg = Debug|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Debug|x86.Build.0 = Debug|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Release|Any CPU.ActiveCfg = Release|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Release|Any CPU.Build.0 = Release|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Release|x64.ActiveCfg = Release|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Release|x64.Build.0 = Release|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Release|x86.ActiveCfg = Release|Any CPU + {3120575A-19FC-4615-B46F-2220250D3F6C}.Release|x86.Build.0 = Release|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Debug|Any CPU.Build.0 = Debug|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Debug|x64.ActiveCfg = Debug|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Debug|x64.Build.0 = Debug|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Debug|x86.ActiveCfg = Debug|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Debug|x86.Build.0 = Debug|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Release|Any CPU.ActiveCfg = Release|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Release|Any CPU.Build.0 = Release|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Release|x64.ActiveCfg = Release|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Release|x64.Build.0 = Release|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Release|x86.ActiveCfg = Release|Any CPU + {934F750B-9A32-461C-8408-515434A645FF}.Release|x86.Build.0 = Release|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Debug|Any CPU.Build.0 = Debug|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Debug|x64.ActiveCfg = Debug|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Debug|x64.Build.0 = Debug|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Debug|x86.ActiveCfg = Debug|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Debug|x86.Build.0 = Debug|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Release|Any CPU.ActiveCfg = Release|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Release|Any CPU.Build.0 = Release|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Release|x64.ActiveCfg = Release|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Release|x64.Build.0 = Release|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Release|x86.ActiveCfg = Release|Any CPU + {BBC3D777-24A2-4F1A-AFFD-EB20C7951C62}.Release|x86.Build.0 = Release|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Debug|Any CPU.Build.0 = Debug|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Debug|x64.ActiveCfg = Debug|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Debug|x64.Build.0 = Debug|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Debug|x86.ActiveCfg = Debug|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Debug|x86.Build.0 = Debug|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Release|Any CPU.ActiveCfg = Release|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Release|Any CPU.Build.0 = Release|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Release|x64.ActiveCfg = Release|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Release|x64.Build.0 = Release|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Release|x86.ActiveCfg = Release|Any CPU + {178A6DDD-0448-4D1D-A794-19BA8E8C55AD}.Release|x86.Build.0 = Release|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Debug|Any CPU.Build.0 = Debug|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Debug|x64.ActiveCfg = Debug|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Debug|x64.Build.0 = Debug|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Debug|x86.ActiveCfg = Debug|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Debug|x86.Build.0 = Debug|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Release|Any CPU.ActiveCfg = Release|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Release|Any CPU.Build.0 = Release|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Release|x64.ActiveCfg = Release|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Release|x64.Build.0 = Release|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Release|x86.ActiveCfg = Release|Any CPU + {C4C04C75-3BF1-465A-B73E-8099203FFB65}.Release|x86.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE