# soaprs
`soaprs` is an idiomatic Rust interpretation of the architectural ideas behind
[`@soapjs/soap`](https://github.com/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:
```toml
[dependencies]
soaprs = "0.1"
```
Define application operations without depending on an asynchronous runtime or
transport framework in the core contract:
```rust
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`](https://github.com/soaprs/soap/tree/main/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
```bash
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
cargo run -p soaprs-users-memory-example
```
See the [documentation index](https://github.com/soaprs/soap/blob/main/docs/README.md),
the [architecture overview](https://github.com/soaprs/soap/blob/main/docs/architecture/OVERVIEW.md),
the [roadmap](https://github.com/soaprs/soap/blob/main/docs/architecture/ROADMAP.md),
and the [changelog](https://github.com/soaprs/soap/blob/main/CHANGELOG.md).