Skip to content

Commit

Permalink
doc: updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
brizzbuzz committed Jan 8, 2022
1 parent 610d565 commit d2f31e3
Showing 1 changed file with 2 additions and 135 deletions.
137 changes: 2 additions & 135 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,139 +27,6 @@ but they are by no means mandatory. However, if you write an awesome generator
would love, please open an issue [here](https://github.com/unredundant/satisfaketion/issues) to discuss adding it
to the repository

If you want to get a little spicy 🤠 every merge of Satisfaketion is published to the GitHub package registry. Pulling
from GitHub is slightly more involved, but such is the price you pay for bleeding edge fake data generation.
## Documentation

```kotlin
// 1 set up a helper function to import any GitJub Repository Package
// This step is optional, but I have a bunch of stuff stored on GitHub, so I find it useful 😄
fun RepositoryHandler.github(packageUrl: String) = maven {
name = "GithubPackages"
url = uri(packageUrl)
credentials {
username = java.lang.System.getenv("GITHUB_USER")
password = java.lang.System.getenv("GITHUB_TOKEN")
}
}

// 2 Add the repo in question (in this case Kompendium)
repositories {
github("https://maven.pkg.github.com/unredundant/satisfaketion")
}

// 3 Add the package like any normal dependency
dependencies {
implementation("io.bkbn:satisfaketion-core:latest.snapshot")
}

```

## In Depth 👀

Satisfaketion is broken into three main library modules

- Core
- Generators
- Mutators

### Core

The engine that powers Satisfaketion. Instantiating a satisfaketion object is as easy as declaring the helper function.

Once a class has been registered, type-safe generators can be associated with each member of the class.

```kotlin
val satisfaketion = satisfaketion {
register(SimpleDataClass::class) {
SimpleDataClass::a { TestPhoneGenerator }
SimpleDataClass::b { SmolIntGenerator }
}
}

val example = satisfaketion.generate<SimpleDataClass>()
```

A `Generator` is a functional interface that declares a single method `generate`

```kotlin
fun interface Generator<R> {
fun generate(seed: Random): R
}
```

An example generator for a naive phone number could be

```kotlin
object TestPhoneGenerator : Generator<String> {
override fun generate(seed: Random = Random.Default): String {
val first = random.nextInt(100..999)
val second = random.nextInt(100..999)
val third = random.nextInt(1000..9999)
return "$first-$second-$third"
}
}
```

Another concept that is at the core of `Satisfaketion` is the `Mutator`.

A `Mutator` is another functional interface

```kotlin
fun interface Mutator<R, RR> {
fun mutate(generator: Generator<R>): Generator<RR>
}
```

Mutators allow you to take an existing `Generator` and mutate it, allowing for expansive reuse of base generators.

Let's say you have a data class `MyPerson`

```kotlin
data class MyPerson(
val firstName: String,
val lastName: String,
val prefix: String?,
val suffix: String?,
)
```

using the existing `EnglishName` generator, you can declare a satisfaketion instance, with mutators to add weighted mutability to the `prefix` and `suffix` fields

```kotlin
val satisfaketion = satisfaketion {
register(MyPerson::class) {
MyPerson::firstName { EnglishName.firstName }
MyPerson::lastName { EnglishName.lastName }
MyPerson::prefix { nameGenerator.prefix.mutate(WeightedNullabilityMutator(0.25, seed)) }
MyPerson::suffix { nameGenerator.suffix.mutate(WeightedNullabilityMutator(0.25, seed)) }
}
}
```

This would cause approximately 25% of generated objects to have a null field for `prefix` and/or `suffix`

### Generators ♺

Collection of useful generators to create fantastic fake data

The current list of pre-existing generators is

- English Names
- United States Address
- Beer
- Barcodes

If you would like to add a generator, please first open an issue [here](https://github.com/unredundant/satisfaketion/issues) explaining the use case.

### Mutators 🦋

Collection of useful mutators

- `WeightedNullabilityMutator`: Given a weight between 0 and 1, will mutate a generator to provided interspersed null values in accordance with the provided weight
- `CollectionMutator`: Takes a standard generator and converts it to a `List` generator

## Limitations 🚨

Due to the reflective operations that satisfaketion performs, it will not work on non-public data classes.

With that said, for internal classes, individual generators can still be used and applied directly to members
All documentation for the library is kept [here](https://unredundant.github.io/satisfaketion/index.html)

0 comments on commit d2f31e3

Please sign in to comment.