soaprs

soaprs is an idiomatic Rust interpretation of the architectural ideas behind @soapjs/soap. It provides small contracts for Clean Architecture applications without a runtime dependency-injection container, reflection, or framework-specific types in the core.

The project is at an early design and contract-validation stage. Releases in the 0.1.x line are previews and their public API is not stable yet.

Development is pinned to Rust 1.97.1 and Edition 2024. The workspace supports Rust 1.85.0 or newer; CI verifies both the MSRV and the current stable toolchain.

Current scope

The first release provides:

object-safe asynchronous use-case and named-query contracts,
DDD-friendly entities and constructor-injected ports,
read and read-write repository contracts,
a database-independent query AST with documented semantics,
structured errors with preserved technical sources and diagnostic IDs,
transport-neutral HTTP metadata and default error mapping,
a reference in-memory adapter and reusable adapter contract tests.

Production database and web-framework adapters are not included in the current release. They will be published as separate crates after their corresponding ports and executable contract tests are ready.

Quick start

Add the facade crate:

[dependencies]
soaprs = "0.1"

Define application operations without depending on an asynchronous runtime or transport framework in the core contract:

use soaprs::prelude::{BoxFuture, SoapResult, UseCase};

struct WelcomeUser;

impl UseCase for WelcomeUser {
    type Input = String;
    type Output = String;

    fn execute(&self, name: Self::Input) -> BoxFuture<'_, SoapResult<Self::Output>> {
        Box::pin(async move { Ok(format!("Welcome, {name}!")) })
    }
}

The complete example shows validation, write repositories, portable named queries, constructor injection, and an in-memory adapter in one application: examples/users-memory.

Workspace

soaprs-core — structured errors with preserved diagnostic sources, entities, boxed futures, use cases, and named-query contracts.
soaprs-repository — validated fields, query AST, repository ports, and a reusable handler for portable named queries.
soaprs-http — transport-neutral endpoint metadata and HTTP error mapping.
soaprs — convenience facade and prelude.
soaprs-contract-tests — reusable behavioral checks for repository adapters.
soaprs-memory — reference in-memory adapter.
users-memory — runnable example with use cases, portable named queries, constructor injection, and the in-memory adapter.

Planned ecosystem

The following crates are planned and are not part of the current release:

soaprs-axum — Axum HTTP adapter,
soaprs-sqlx — SQLx and PostgreSQL adapter,
soaprs-mongodb — MongoDB adapter,
soaprs-redis — Redis repository and cache adapters,
soaprs-events — event bus, command, and CQRS contracts,
soaprs-cli and cargo-soap — project and module generation.

The roadmap describes direction rather than release dates. Framework, database, cache, and broker adapters will live in separate repositories after their ports stabilize.

Development

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
cargo run -p soaprs-users-memory-example