You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+25-33Lines changed: 25 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,8 +44,8 @@
44
44
---
45
45
46
46
-[Purpose](#purpose)
47
-
*[Easy Consistency as Toolings](#easy-consistency-as-toolings)
48
-
*[Business Logic as Self-Expanatory Code](#business-logic-as-self-expanatory-code)
47
+
*[Automated Observability and Error Handling](#automated-observability-and-error-handling)
48
+
*[Self-Expanatory Business Logic](#self-expanatory-business-logic)
49
49
*[JavaScript Decorators At Its Best](#javascript-decorators-at-its-best)
50
50
-[How to Use](#how-to-use)
51
51
*[Install](#install)
@@ -55,7 +55,6 @@
55
55
*[Extension](#extension)
56
56
*[Opinionated Function Signature](#opinionated-function-signature)
57
57
*[Refactor](#refactor)
58
-
*[Without Decorator and Pipe Operators](#without-decorator-and-pipe-operators)
59
58
-[Integration](#integration)
60
59
*[Integrate with Server Frameworks](#integrate-with-server-frameworks)
61
60
*[Integrate with Redux](#integrate-with-redux)
@@ -66,9 +65,9 @@
66
65
67
66
### Purpose
68
67
69
-
#### Easy Consistency as Toolings
68
+
#### Automated Observability and Error Handling
70
69
71
-
By packing all standardisable patterns such as observarability, error handling, etc. as reusable decorators, it promotes and ensures consistency across micro-services and teams. This greatly improves the monitor efficiency and debugging or maintainance experience.
70
+
By packing all standardisable patterns such as observarability, error handling, etc. as reusable decorators, it promotes and ensures consistency across micro-services and teams. This greatly improves the monitor clarity and debugging/maintainance experience.
72
71
73
72
74
73
```js
@@ -92,26 +91,40 @@ class SubscriptionAPI
92
91
/* handler.js - an illustration of the business logic */
> Thanks to the [opionated function signature](#opinionated-function-signature), those decorators work out of box with minimum configuration to create a calling stack tree using the exact names of the decorated functions, producing structured log, metrics, tracing.
103
100
104
-
The structured log it produced below makes it a breeze to precisely pinpoint the error function with param to reproduce the case. This can be easily further integrated into an automated cross-team monitoring and alerting system.
101
+
The structured log it produced below makes it a breeze to precisely pinpoint the error function with param to reproduce the case. This can be easily further integrated into an automated cross-team monitoring and alerting/debugging system.
> Those decorators work out of box with minimum configuration thanks to the [opionated functionsignature](
112
-
#opinionated-function-signature). They also work nicely [without @, |> operators](#without-decorator-and-pipe-operators).
108
+
> We are calling those decorators **hooks(decorators at call-time beside definition-time)** to indicate that they can be used at any point of a business logic functionlifecycle to extend highly flexible and precise control.
109
+
110
+
```js
111
+
/* handler.js - configure and attach hooks to business logic steps with hookEachPipe */
112
+
import { pipeHookEach, eventLogger, eventTimer } from '@opbi/hooks';
113
+
import { UserProfileAPI, SubscriptionAPI } from './api.js';
// all with default configuration applied to each step below
117
+
eventLogger(), eventTimer()
118
+
)(
119
+
UserProfileAPI.getSubscription,
120
+
// precise control with step only hook
121
+
chain(
122
+
errorRetry({ condition: e => e.type === 'TimeoutError' })
123
+
)(SubscriptionAPI.cancel),
124
+
);
125
+
```
113
126
114
-
#### Business Logic as Self-Expanatory Code
127
+
#### Self-Expanatory Business Logic
115
128
116
129
By abstract out all common control mechanism and observability code into well-tested, composable decorators, this also helps to achieve codebase that is self-explanatory of its business logic and technical behaviour by the names of functions and decorators. This is great for testing and potentially rewrite the entire business logic functions as anything other than business logic is being packed into well-tested reusable decorators, which can be handily mocked during test.
117
130
@@ -189,27 +202,6 @@ function (param, meta, context) {}
189
202
#### Refactor
190
203
To help adopting the hooks by testing them out with minimal refactor on non-standard signature functions, there's an unreleased [adaptor](https://github.com/opbi/toolchain/blob/adapator-non-standard/src/hooks/adaptors/nonstandard.js) to bridge the function signatures. It is not recommended to use this for anything but trying the hooks out, especially observability hooks are not utilised this way.
191
204
192
-
#### Without Decorator and Pipe Operators
193
-
194
-
> We are calling those decorators **hooks(decorators at call-time beside definition-time)** to indicate that they can be used at any point of a business logic function lifecycle to extend highly flexible and precise control.
195
-
196
-
```js
197
-
/* handler.js - configure and attach hooks to business logic steps with hookEachPipe */
198
-
import { pipeHookEach, eventLogger, eventTimer } from '@opbi/hooks';
199
-
import { UserProfileAPI, SubscriptionAPI } from './api.js';
0 commit comments