## Examples
The following examples outline the general usage of both the immutable and mutable API of *datus*.
Please refer to the [USAGE.md](https://github.com/roookeee/datus/blob/master/USAGE.md) for an extensive guide on *datus*
that includes [a fictional, more complex scenario with changing requirements](https://github.com/roookeee/datus/blob/master/USAGE.md#examples).
#### Immutable object API example
```java

class Person {
//getters + constructor omitted for brevity
private final String firstName;
private final String lastName;

}

class PersonDTO {
//getters omitted for brevity
private final String firstName;
private final String lastName;

public PersonDTO(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}
}

//define a building process for each constructor parameter, step by step
//the immutable API defines constructor parameters in their declaration order
Mapper mapper = Datus.forTypes(Person.class, PersonDTO.class).immutable(PersonDTO::new)
.from(Person::getFirstName).to(ConstructorParameter::bind)
.from(Person::getLastName).nullsafe()
.given(String::isEmpty, "fallback").orElse(ln -> ln.toUpperCase())
.to(ConstructorParameter::bind)
.build();

Person person = new Person();
person.setFirstName("firstName");
person.setLastName(null);
PersonDTO personDto = mapper.convert(person);
/*
personDto = PersonDTO [
firstName = "firstName",
lastName = null
]
*/
person.setLastName("");
personDto = mapper.convert(person);
/*
personDto = PersonDTO [
firstName = "firstName",
lastName = "fallback"
]
*/
person.setLastName("lastName");
personDto = mapper.convert(person);
/*
personDto = PersonDTO [
firstName = "firstName",
lastName = "LASTNAME"
]
*/
```

#### Mutable object API example
```java
class Person {
//getters + setters omitted for brevity
private String firstName;
private String lastName;
}

class PersonDTO {
//getters + setters + empty constructor omitted for brevity
private String firstName;
private String lastName;
}

//the mutable API defines a mapping process by multiple getter-setter steps
Mapper mapper = Datus.forTypes(Person.class, PersonDTO.class).mutable(PersonDTO::new)
.from(Person::getFirstName).into(PersonDTO.setFirstName)
.from(Person::getLastName).nullsafe()
.given(String::isEmpty, "fallback").orElse(ln -> ln.toUpperCase())
.into(PersonDTO::setLastName)
.from(/*...*/).into(/*...*/)
.build();

Person person = new Person();
person.setFirstName("firstName");
person.setLastName(null);
PersonDTO personDto = mapper.convert(person);
/*
personDto = PersonDTO [
firstName = "firstName",
lastName = null
]
*/
person.setLastName("");
personDto = mapper.convert(person);
/*
personDto = PersonDTO [
firstName = "firstName",
lastName = "fallback"
]
*/
person.setLastName("lastName");
personDto = mapper.convert(person);
/*
personDto = PersonDTO [
firstName = "firstName",
lastName = "LASTNAME"
]
*/
```
## Sample projects
There are two sample projects located in the [sample-projects](https://github.com/roookeee/datus/tree/master/sample-projects) directory
that showcase most of *datus* features in two environments: [framework-less](https://github.com/roookeee/datus/tree/master/sample-projects/plainjava)
and [with Spring Boot](https://github.com/roookeee/datus/tree/master/sample-projects/samplespring).

Hop right in and tinker around with *datus* in a compiling environment!

## User guide
Please refer to the [USAGE.md](https://github.com/roookeee/datus/blob/master/USAGE.md) for a complete user guide as the readme only serves as a broad overview.
The user guide is designed to take **at most 15 minutes** to get you covered on everything about *datus* and how to use it
in different scenarios.

## Dependency information
Maven
```xml

com.github.roookeee
datus
1.5.0

```
or any other build system via Maven Central

[](https://search.maven.org/search?q=g:%22com.github.roookeee%22%20AND%20a:%22datus%22)

## Supported JVM languages
*datus* currently only supports Java as every other popular statically typed language on the JVM has fundamental issues with *datus*
core workflow. Non-statically typed languages like Clojure are not tested for compatability.

##### Kotlin issues
Kotlin has a myriad of issues when it comes to the type-inference chain of *datus* builder-like API which makes 1:1 translations
of Java to Kotlin (e.g. immutable class to data class) uncompilable. The encoding
of (non-) nullability in Kotlins type system makes using method references with *datus* nearly impossible when using a nullable type
and referencing Java functions from Kotlin (e.g. something simple as `Long::parseLong` on a `Long?`).

##### Scala issues
Scala offers no way to obtain a method reference to a constructor of an object which forces *datus* users to provide
a lambda which delegates to the corresponding constructor. This lambda has to be fully typed as Scalas overload resolution
/ type-inference cannot handle it otherwise. This makes using the immutable API of datus cumbersome which is especially
bad for a language like Scala that is focused around immutability.

The aforementioned issues are not exhaustive and more issues are likely to arise when working around them.
Therefor it is discouraged to use *datus* in any other language than Java right now.

## Development principles
This section is about the core principles *datus* is developed with.

#### Benchmarking
Every release of *datus* is monitored for performance regressions by a simple JMH suite that checks the core
functionality of datus (simple mapping from `a->b`).
See `com.github.roookeee.datus.performance.PerformanceBenchmarkTest` for further insight.

#### Mutation testing
*datus* uses [pitest](http://pitest.org/) to secure the quality of all implemented tests and has no surviving mutations outside
of `Datus` helper functions (which only aid type inference and are thus not tested), some constructors of the immutable API that only
delegate and are thus not explicitly tested and pitest edge-cases which are not testable / programmatically producible.

#### Branching
The `master` branch always matches the latest release of *datus* while the `develop` branch houses the next version of datus
that is still under development.

#### Semver
*datus* follows semantic versioning (see https://semver.org/) starting with the 1.0 release.

#### Licensing
*datus* is licensed under The MIT License (MIT)

Copyright (c) 2019-2023 Nico Heller

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

## Supporting datus development
Like *datus* ? Consider buying me a coffee :)