11<p align =" center " ><img src =" https://user-images.githubusercontent.com/5921929/73911149-1dad9280-4866-11ea-8818-fed1cd49e8b1.png " width =" 360 " ></p >
22
33# work
4+
45> A compact library for tracking and committing atomic changes to your entities.
56
67[ ![ GoDoc] [ doc-img ]] [ doc ] [ ![ Build Status] [ ci-img ]] [ ci ]
1617### Construction
1718
1819Starting with entities ` Foo ` and ` Bar ` ,
20+
1921``` go
2022// entities.
2123f , b := Foo {}, Bar {}
@@ -32,36 +34,46 @@ unit, err := unit.New(opts...)
3234```
3335
3436### Adding
37+
3538When creating new entities, use [ ` Add ` ] [ unit-doc ] :
39+
3640``` go
3741additions := []interface {}{ f, b }
3842err := u.Add (additions...)
3943```
4044
4145### Updating
46+
4247When modifying existing entities, use [ ` Alter ` ] [ unit-doc ] :
48+
4349``` go
4450updates := []interface {}{ f, b }
4551err := u.Alter (updates...)
4652```
4753
4854### Removing
55+
4956When removing existing entities, use [ ` Remove ` ] [ unit-doc ] :
57+
5058``` go
5159removals := []interface {}{ f, b }
5260err := u.Remove (removals...)
5361```
5462
55- ### Registering
63+ ### Registering
64+
5665When retrieving existing entities, track their intial state using
5766[ ` Register ` ] [ unit-doc ] :
67+
5868``` go
5969fetched := []interface {}{ f, b }
6070err := u.Register (fetched...)
6171```
6272
6373### Saving
74+
6475When you are ready to commit your work unit, use [ ` Save ` ] [ unit-doc ] :
76+
6577``` go
6678ctx := context.Background ()
6779err := u.Save (ctx)
@@ -89,16 +101,18 @@ l, _ := zap.NewDevelopment()
89101opts = []unit.Option {
90102 unit.DB (db),
91103 unit.DataMappers (m),
92- unit.Logger (l), // 🎉
104+ unit.ZapLogger (l), // 🎉
93105}
94106u , err := unit.New (opts...)
95107```
96108
97109### Metrics
110+
98111For emitting metrics, we use [ ` tally ` ] [ tally ] . To utilize the metrics emitted
99112from the work units, leverage the [ ` unit.Scope ` ] [ unit-scope-doc ] option
100113with a [ ` tally.Scope ` ] [ scope-doc ] upon creation. Assuming we have a
101114scope ` s ` , it would look like so:
115+
102116``` go
103117opts = []unit.Option {
104118 unit.DB (db),
@@ -112,25 +126,27 @@ u, err := unit.New(opts...)
112126
113127<p align =" center " ><img src =" https://user-images.githubusercontent.com/5921929/106403546-191daa80-63e4-11eb-98b5-6b5d1989bacb.gif " width =" 960 " ></p >
114128
115- | Name | Type | Description |
116- | -------------------------------- | ------- | ------------------------------------------------------------ |
117- | [ _ PREFIX._ ] unit.save.success | counter | The number of successful work unit saves. |
118- | [ _ PREFIX._ ] unit.save | timer | The time duration when saving a work unit. |
119- | [ _ PREFIX._ ] unit.rollback.success | counter | The number of successful work unit rollbacks. |
120- | [ _ PREFIX._ ] unit.rollback.failure | counter | The number of unsuccessful work unit rollbacks. |
121- | [ _ PREFIX._ ] unit.rollback | timer | The time duration when rolling back a work unit. |
122- | [ _ PREFIX._ ] unit.retry.attempt | counter | The number of retry attempts. |
123- | [ _ PREFIX._ ] unit.insert | counter | The number of successful inserts performed. |
124- | [ _ PREFIX._ ] unit.update | counter | The number of successful updates performed. |
125- | [ _ PREFIX._ ] unit.delete | counter | The number of successful deletes performed. |
126- | [ _ PREFIX._ ] unit.cache.insert | counter | The number of registered entities inserted into the cache. |
127- | [ _ PREFIX._ ] unit.cache.delete | counter | The number of registered entities removed from the cache. |
129+ | Name | Type | Description |
130+ | -------------------------------- | ------- | ---------------------------------------------------------- |
131+ | [ _ PREFIX._ ] unit.save.success | counter | The number of successful work unit saves. |
132+ | [ _ PREFIX._ ] unit.save | timer | The time duration when saving a work unit. |
133+ | [ _ PREFIX._ ] unit.rollback.success | counter | The number of successful work unit rollbacks. |
134+ | [ _ PREFIX._ ] unit.rollback.failure | counter | The number of unsuccessful work unit rollbacks. |
135+ | [ _ PREFIX._ ] unit.rollback | timer | The time duration when rolling back a work unit. |
136+ | [ _ PREFIX._ ] unit.retry.attempt | counter | The number of retry attempts. |
137+ | [ _ PREFIX._ ] unit.insert | counter | The number of successful inserts performed. |
138+ | [ _ PREFIX._ ] unit.update | counter | The number of successful updates performed. |
139+ | [ _ PREFIX._ ] unit.delete | counter | The number of successful deletes performed. |
140+ | [ _ PREFIX._ ] unit.cache.insert | counter | The number of registered entities inserted into the cache. |
141+ | [ _ PREFIX._ ] unit.cache.delete | counter | The number of registered entities removed from the cache. |
128142
129143### Uniters
144+
130145In most circumstances, an application has many aspects that result in the
131146creation of a work unit. To tackle that challenge, we recommend using
132147[ ` unit.Uniter ` ] [ uniter-doc ] to create instances of [ ` unit. ` ] [ unit-doc ] ,
133148like so:
149+
134150``` go
135151opts = []unit.Option {
136152 unit.DB (db),
0 commit comments