Skip to content

Commit

Permalink
Update documentation. (#69)
Browse files Browse the repository at this point in the history
  • Loading branch information
fr33r authored Sep 21, 2022
1 parent 5b3993f commit f79a34e
Show file tree
Hide file tree
Showing 2 changed files with 82 additions and 11 deletions.
57 changes: 50 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,35 @@ For SQL datastores, also enjoy:

## Release information

### [4.0.0-beta][v4.0.0-beta]
| Version | Supported | Documentation |
|---------|-----------|-------------------------------|
| `V4` || [See][v4-docs] `v4/README.md` |
| `V3` || None |
| `V2` || None |
| `V1` || None |

### V4

#### [4.0.0-beta.3][v4.0.0-beta.3]

- Various dependency upgrades to address vulnerability [alerts][dependabot-alerts].
- Upgraded `github.com/uber-go/tally` dependency to version `v3.4.2`.
- Upgraded `github.com/stretchr/testify` dependency to version `v1.8.0`.
- Upgraded `go.uber.org/zap` dependency to version `v1.21.1`.

#### [4.0.0-beta.2][v4.0.0-beta.2]

- Introduce initial round of benchmarks.
- Introduce support for 4 more additional metrics.
- `unit.retry.attempt`
- `unit.insert`
- `unit.update`
- `unit.delete`
- Improve documentation & switch to pkg.go.dev.
- Introduce metric demo.
- `make demo`

#### [4.0.0-beta][v4.0.0-beta]

- Introduce `unit` package for aliasing.
- Reduces API footprint.
Expand All @@ -53,22 +81,31 @@ For SQL datastores, also enjoy:
create based on provided options.
- Reconsolidate uniter functionality.

### [3.2.0][v3.2.0]
### V3

#### [3.2.1][v3.2.1]

- Various dependency upgrades to address vulnerability [alerts][dependabot-alerts].
- Upgraded `github.com/uber-go/tally` dependency to version `v3.4.2`.
- Upgraded `github.com/stretchr/testify` dependency to version `v1.8.0`.
- Upgraded `go.uber.org/zap` dependency to version `v1.21.1`.

#### [3.2.0][v3.2.0]

- Introduce [lifecycle actions][actions-pr].
- Introduce [concurrency support][concurrency-pr].

### [3.0.0][v3.0.0]
#### [3.0.0][v3.0.0]

- Introduce support for Go modules.

### 2.x.x
### V2

- NO LONGER SUPPORTED. CODE REMOVED.
- NO LONGER SUPPORTED. CODE REMOVED. SEE `v2.x.x` [TAGS][tags].

### 1.x.x
### V1

- NO LONGER SUPPORTED. CODE REMOVED.
- NO LONGER SUPPORTED. CODE REMOVED. SEE `v1.x.x` [TAGS][tags].

> Versions `1.x.x` and `2.x.x` are no longer supported. Please upgrade to
`3.x.x+` to receive the latest and greatest features, such as
Expand Down Expand Up @@ -118,6 +155,12 @@ how we do things.
[release-img]: https://img.shields.io/github/tag/freerware/work.svg?label=version
[blog]: https://medium.com/@freerjm/work-units-ec2da48cf574
[blog-img]: https://img.shields.io/badge/blog-medium-lightgrey
[v4-docs]: https://github.com/freerware/work/blob/master/v4/README.md
[v3.2.0]: https://github.com/freerware/work/releases/tag/v3.2.0
[v3.2.1]: https://github.com/freerware/work/releases/tag/v3.2.1
[v3.0.0]: https://github.com/freerware/work/releases/tag/v3.0.0
[v4.0.0-beta]: https://github.com/freerware/work/releases/tag/v4.0.0-beta
[v4.0.0-beta.2]: https://github.com/freerware/work/releases/tag/v4.0.0-beta.2
[v4.0.0-beta.3]: https://github.com/freerware/work/releases/tag/v4.0.0-beta.3
[tags]: https://github.com/freerware/work/tags
[dependabot-alerts]: https://github.com/freerware/work/security/dependabot?q=is%3Aclosed
36 changes: 32 additions & 4 deletions v4/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,32 @@ uniter := unit.NewUniter(opts...)
u, err := uniter.Unit()
```

## Frequently Asked Questions (FAQ)

### Are batch data mapper operations supported?

In short, yes.

A work unit can accommodate an arbitrary number of entity types. When creating
the work unit, you indicate the data mappers that it should use when persisting
the desired state. These data mappers are organized by entity type. As such,
batching occurs for each operation and entity type pair.

For example, assume we have a single work unit and have performed a myriad
of unit operations for entities with either a type of `Foo` or `Bar`. All inserts
for entities of type `Foo` will be [passed][insert-method-ref] to the corresponding data mapper in
one shot via the `Insert` [method][insert-method]. This essentially then relinquishes control to you,
the author of the data mapper, to handle all of those entities to be inserted
in however you see fit. You could choose to insert them all into a relational
database using a single `INSERT` query, or perhaps issue an HTTP request to
an API to create all of those entities. However, inserts for entities of type
`Bar` will be batched separately. In fact, it's most likely the data mapper to handle
inserts for `Foo` and `Bar` are completely different types (and maybe even
completely different data stores).

The same applies for other operations such as updates and deletions. All
supported data mapper operations follow this paradigm.

[uow]: https://martinfowler.com/eaaCatalog/unitOfWork.html
[sql-data-mapper-doc]: https://godoc.org/github.com/freerware/work#SQLDataMapper
[data-mapper-doc]: https://godoc.org/github.com/freerware/work#DataMapper
Expand All @@ -151,13 +177,15 @@ u, err := uniter.Unit()
[code-of-conduct]: https://github.com/freerware/work/blob/master/CODE_OF_CONDUCT.md
[doc-img]: https://pkg.go.dev/badge/github.com/freerware/work/v4.svg
[doc]: https://pkg.go.dev/github.com/freerware/work/v4
[ci-img]: https://travis-ci.org/freerware/work.svg?branch=master
[ci]: https://travis-ci.org/freerware/work
[coverage-img]: https://coveralls.io/repos/github/freerware/work/badge.svg?branch=master
[coverage]: https://coveralls.io/github/freerware/work?branch=master
[ci-img]: https://github.com/freerware/work/actions/workflows/ci.yaml/badge.svg?branch=master
[ci]: https://github.com/freerware/work/actions/workflows/ci.yaml
[coverage-img]: https://codecov.io/gh/freerware/work/branch/master/graph/badge.svg?token=W5YH9TPP3C
[coverage]: https://codecov.io/gh/freerware/work
[license]: https://opensource.org/licenses/Apache-2.0
[license-img]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
[release]: https://github.com/freerware/work/releases
[release-img]: https://img.shields.io/github/tag/freerware/work.svg?label=version
[blog]: https://medium.com/@freerjm/work-units-ec2da48cf574
[blog-img]: https://img.shields.io/badge/blog-medium-lightgrey
[insert-method]: https://github.com/freerware/work/blob/v4.0.0-beta.2/v4/data_mapper.go#L22
[insert-method-ref]: https://github.com/freerware/work/blob/v4.0.0-beta.2/v4/best_effort_unit.go#L137

0 comments on commit f79a34e

Please sign in to comment.