From cf9937046fcd2359830071554863f2ca7869951f Mon Sep 17 00:00:00 2001 From: Nicolas Froidure Date: Sun, 20 Aug 2023 11:55:06 +0200 Subject: [PATCH] docs(architecture): fix and complete architecture docs --- ARCHITECTURE.md | 67 +++++++++++++++++++++++++++++++++---------------- src/counter.ts | 2 +- src/delay.ts | 4 +-- src/importer.ts | 6 +++++ src/lock.ts | 5 ++-- src/log.ts | 4 +-- src/random.ts | 4 +-- src/resolve.ts | 6 +++++ src/time.ts | 2 +- 9 files changed, 68 insertions(+), 32 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 37615b1..7302b2e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -8,13 +8,15 @@ ## Summary 1. [Services](#1-services) - 1. [Logging](#11-logging) + 1. [Log](#11-log) 2. [Time](#12-time) - 3. [Randomness](#13-randomness) - 4. [Delaying](#14-delaying) - 6. [Counter](#16-counter) + 3. [Random](#13-random) + 4. [Delay](#14-delay) + 5. [Resolve](#15-resolve) + 6. [Importer](#16-importer) 7. [Code generator](#17-code-generator) 8. [Lock](#18-lock) + 9. [Counter](#19-counter) ## 1. Services @@ -33,9 +35,9 @@ Their goal is to encapsulate unpredictible states and -### 1.1. Logging +### 1.1. Log -I prefer using a unique function with the log type +I prefer using a unique function with the `log` type in parameter instead of several methods for each log types. It is far easyer to mock and to assert on logs in my tests. @@ -49,7 +51,7 @@ If provided, I route debug messages to the `debug` ### 1.2. Time -The time service is just proxying [`Date.now` +The `time` service is just proxying [`Date.now` ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date/now) in a stubbable manner. @@ -57,9 +59,9 @@ The time service is just proxying [`Date.now` -### 1.3. Randomness +### 1.3. Random -The random service is just proxying [`Math.random` +The `random` service is just proxying [`Math.random` ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in a stubbable manner. @@ -67,26 +69,32 @@ The random service is just proxying [`Math.random` -### 1.4. Delaying +### 1.4. Delay -The delay service is `setTimeout` like I would like it +The `delay` service is `setTimeout` like I would like it to be. [See in context](./src/delay.ts#L18-L22) -### 1.6. Counter +### 1.5. Resolve -The `counter` service provide a simple, local and - stubbable counter. +The `resolve` service is just proxying [`import.meta.resolve` +](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Operators/import.meta/resolve) + in a stubbable manner. -The count are returned asynchronously in order - to be easily maintained across several instances - if needed later via another service with the same - surface API. +[See in context](./src/resolve.ts#L8-L13) -[See in context](./src/counter.ts#L23-L32) + + +### 1.6. Importer + +The `importer` service is just proxying [`import` +](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Operators/import) + in a stubbable manner. + +[See in context](./src/importer.ts#L9-L14) @@ -103,8 +111,9 @@ The `codeGenerator` service provide a service ### 1.8. Lock -This service allows to maintain a lock on a given resource in order - to ensure a sequential access to it in asynchronous code. +The `lock` service allows to maintain a lock on a given + resource in order to ensure a sequential access to it in + asynchronous code. The release is done by its key and the current lock is removed. There is no check on the fact the lock is well released. By design, it is @@ -112,5 +121,19 @@ The release is done by its key and the current lock is removed. There said, it should not be hard to handle since the actual behavior of the library makes your code run sequentially. -[See in context](./src/lock.ts#L28-L38) +[See in context](./src/lock.ts#L28-L39) + + + +### 1.9. Counter + +The `counter` service provide a simple, local and + stubbable counter. + +The count are returned asynchronously in order + to be easily maintained across several instances + if needed later via another service with the same + surface API. + +[See in context](./src/counter.ts#L23-L32) diff --git a/src/counter.ts b/src/counter.ts index e5080f2..4cf2135 100644 --- a/src/counter.ts +++ b/src/counter.ts @@ -20,7 +20,7 @@ const DEFAULT_COUNTER = { firstCount: 1, }; -/* Architecture Note #1.6: Counter +/* Architecture Note #1.9: Counter The `counter` service provide a simple, local and stubbable counter. diff --git a/src/delay.ts b/src/delay.ts index f67d36a..f6b10ec 100644 --- a/src/delay.ts +++ b/src/delay.ts @@ -15,9 +15,9 @@ export interface DelayService { clear: (promise: Promise) => Promise; } -/* Architecture Note #1.4: Delaying +/* Architecture Note #1.4: Delay -The delay service is `setTimeout` like I would like it +The `delay` service is `setTimeout` like I would like it to be. */ diff --git a/src/importer.ts b/src/importer.ts index ed564d0..cd1c953 100644 --- a/src/importer.ts +++ b/src/importer.ts @@ -6,6 +6,12 @@ function noop(): void { return undefined; } +/* Architecture Note #1.6: Importer + +The `importer` service is just proxying [`import` +](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Operators/import) + in a stubbable manner. +*/ export default singleton(autoService(initImporter)) as typeof initImporter; export type ImporterService = (path: string) => Promise; diff --git a/src/lock.ts b/src/lock.ts index 3c7047d..05e5dd7 100644 --- a/src/lock.ts +++ b/src/lock.ts @@ -27,8 +27,9 @@ export interface LockService { /* Architecture Note #1.8: Lock -This service allows to maintain a lock on a given resource in order - to ensure a sequential access to it in asynchronous code. +The `lock` service allows to maintain a lock on a given + resource in order to ensure a sequential access to it in + asynchronous code. The release is done by its key and the current lock is removed. There is no check on the fact the lock is well released. By design, it is diff --git a/src/log.ts b/src/log.ts index 926ef0a..635783d 100644 --- a/src/log.ts +++ b/src/log.ts @@ -50,9 +50,9 @@ export type LogServiceDependencies = LogServiceConfig & { logger: Logger; }; -/* Architecture Note #1.1: Logging +/* Architecture Note #1.1: Log -I prefer using a unique function with the log type +I prefer using a unique function with the `log` type in parameter instead of several methods for each log types. It is far easyer to mock and to assert on logs in my tests. diff --git a/src/random.ts b/src/random.ts index daa606a..bd049ca 100644 --- a/src/random.ts +++ b/src/random.ts @@ -9,9 +9,9 @@ export interface RandomService { (): number; } -/* Architecture Note #1.3: Randomness +/* Architecture Note #1.3: Random -The random service is just proxying [`Math.random` +The `random` service is just proxying [`Math.random` ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in a stubbable manner. */ diff --git a/src/resolve.ts b/src/resolve.ts index 42111b3..ce80856 100644 --- a/src/resolve.ts +++ b/src/resolve.ts @@ -5,6 +5,12 @@ function noop(): void { return undefined; } +/* Architecture Note #1.5: Resolve + +The `resolve` service is just proxying [`import.meta.resolve` +](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Operators/import.meta/resolve) + in a stubbable manner. +*/ export default singleton(autoService(initResolve)); export type ResolveService = ( diff --git a/src/time.ts b/src/time.ts index 4622dc9..d83a474 100644 --- a/src/time.ts +++ b/src/time.ts @@ -11,7 +11,7 @@ export interface TimeService { /* Architecture Note #1.2: Time -The time service is just proxying [`Date.now` +The `time` service is just proxying [`Date.now` ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date/now) in a stubbable manner. */