Skip to content

Commit

Permalink
SPT-1998 correct mistakes
Browse files Browse the repository at this point in the history
  • Loading branch information
Andrey Frolov authored and mrandrewsmith committed May 24, 2024
1 parent c4bcfd7 commit 767956f
Show file tree
Hide file tree
Showing 7 changed files with 38 additions and 44 deletions.
2 changes: 1 addition & 1 deletion TechDocs/Documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@
- [Chains](/TechDocs/Chains.md)
- [Logging](/TechDocs/Log/Log.md)
- [NodeKitMock](/TechDocs/Testing/NodeKitMock.md)
- [Code documentation](https://surfstudio.github.io/NodeKit/)
- [Code documentation](../docs/index.html)
25 changes: 10 additions & 15 deletions TechDocs/Log/Log.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,27 @@ Out of the box, the library allows logging any operation performed by a node.

## How logging works

The protocol [LoggingContextProtocol](https://surfstudio.github.io/NodeKit/Protocols/LoggingContextProtocol.html), responsible for log storage, is implemented in the actor [LoggingContext](https://surfstudio.github.io/NodeKit/Actors/LoggingContext.html).
The NodeKit library provides the ability to write logs using storage [LoggingContextProtocol](../../docs/Protocols/LoggingContextProtocol.html). The built-in implementation of `LoggingContextProtocol` is [LoggingContext](../../docs/Actors/LoggingContext.html).
`LoggingContext` is created when the `process(_ data: Input)` method of the chain is called and is passed to all nodes through the `process(_ data: Input, logContext: LoggingContextProtocol)` method. Thus, each node has the ability to work with the same `LoggingContext`.

`LoggingContext` is created when the `process(_ data: Input)` method of the chain is called and is passed to all nodes in the `process(_ data: Input, logContext: LoggingContextProtocol)` method. Thus, each node has the ability to work with the same `LoggingContext`.
The data type that `LoggingContextProtocol` stores is [Logable](../../docs/Protocols/Logable.html), implemented in the structure [Log](../../docs/Structs/Log.html).
To add a new log, you need to create a `Log` object and pass it to `LoggingContextProtocol` using the `add` method.

`LoggingContextProtocol` stores objects of [Logable](https://surfstudio.github.io/NodeKit/Protocols/Logable.html) protocol , implemented in the structure [Log](https://surfstudio.github.io/NodeKit/Structs/Log.html).

To add a new log, you need to create a `Logable` object and pass it to `LoggingContextProtocol` using the `add` method.

The log itself represents a linked list.
The log itself represents a linked list:

![All text](log_nodes_tree.svg)

This allows us to output logs in the correct order.
This allows us to output logs in the correct order:

![All text](log_chaining.svg)

## Logging Output

The [LoggerNode](https://surfstudio.github.io/NodeKit/Classes/LoggerNode.html) is responsible for logging output to the screen.

The [LoggerNode](../../docs/Classes/LoggerNode.html) is responsible for logging output to the screen.
It is placed at the very beginning of the chain and outputs the message only after the entire chain has finished its work.

This node has a log filtering mode.

It is based on the `id` field of `Logable`. By default, it is equal to the name of the node that created the log. By default, the filter is empty, and all messages are output to the console. To exclude a specific log, you can add the node to the filter, and you can obtain the node's name like this: `CustomNode.objectName`.
The node has a log filtering mode.
It is based on the `id` field of `Logable`. To exclude a specific log, you can add the node to the filter.

By default, logs are output in the following format:
```
Expand All @@ -39,7 +35,6 @@ log message separated by \r\n and \t
```

Custom formatting for custom logs is possible according to personal preferences.

You can configure logging in the `URLChainsBuilder`. More details about this can be found [here](../Chains.md).

## Example
Expand All @@ -62,6 +57,6 @@ func process(_ data: Input, logContext: LoggingContextProtocol) async -> NodeRes

```

Here, at the beginning, we create a log object, initializing it with the message `<<<===\(self.objectName)===>>>` and passing the name of this node as its id.
Here, at the beginning, we create a log object, initializing it with the message `<<<===\(objectName)===>>>` and passing the name of this node as its id.

Then, we add a message about the data operation, and finally, we write the log.
4 changes: 2 additions & 2 deletions TechDocs/MainConcept.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,8 @@ func getUser(by id: String) async -> NodeResult<User> {
}
```

We used here static withMappedExceptions method. It allowed us to map all exceptions to `Faulure` of `NodeResult`.
You can find more details about this and other methods of NodeResult [here](https://surfstudio.github.io/NodeKit/Extensions/NodeResult.html).
We used here static `withMappedExceptions` method. It allowed us to map all exceptions to `Failure` of `NodeResult`.
You can find more details about this and other methods of NodeResult [here](../docs/Extensions/NodeResult.html).

What if we want to map database errors to some custom errors?
Let's write a node for this.
Expand Down
20 changes: 10 additions & 10 deletions TechDocs/Models.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ But it is also allowed to use only one model layer or not to use models at all.

Two protocols are responsible for defining the model from this layer:

1) [RawEncodable](https://surfstudio.github.io/NodeKit/Protocols/RawEncodable.html)
2) [RawDecodable](https://surfstudio.github.io/NodeKit/Protocols/RawDecodable.html)
1) [RawEncodable](../docs/Protocols/RawEncodable.html)
2) [RawDecodable](../docs/Protocols/RawDecodable.html)

There is also an alias [RawMappable](https://surfstudio.github.io/NodeKit/Typealiases.html#/s:10CoreNetKit14RawMappable)
There is also an alias [RawMappable](../docs/Typealiases.html#/s:7NodeKit11RawMappablea)

For entities that conform to the `Codable` protocols, there is a default mapping implementation.

Expand Down Expand Up @@ -63,10 +63,10 @@ This code will be sufficient to map the server response to the `UserEntry` and `

Two protocols are responsible for defining the model from this layer:

1) [DTOEncodable](https://surfstudio.github.io/NodeKit/Protocols/DTOEncodable.html)
2) [DTODecodable](https://surfstudio.github.io/NodeKit/Protocols/DTODecodable.html)
1) [DTOEncodable](../docs/Protocols/DTOEncodable.html)
2) [DTODecodable](../docs/Protocols/DTODecodable.html)

There is also an alias [DTOConvertible](https://surfstudio.github.io/NodeKit/Typealiases.html#/s:10CoreNetKit14DTOConvertiblea)
There is also an alias [DTOConvertible](../docs/Typealiases.html#/s:7NodeKit14DTOConvertiblea)

Example:

Expand Down Expand Up @@ -104,9 +104,9 @@ extension User: DTODecodable {
}
```

Thus, we obtain a pair of two models, where::
1) `UserEntry: RawDecodable` - DTO-Layer.
2) `User: DTODecodable` - App-Layer.
Thus, we obtain a pair of two models, where:
1) `UserEntry: RawDecodable` - DTO-Layer
2) `User: DTODecodable` - App-Layer

#### Good to know

Expand All @@ -133,7 +133,7 @@ And the requirements are as follows:
1) Always output `alias` as the product name.
2) In case `alias == nil` or `alias.isEmpty`, output `name`.

These requirements are due to the fact that `alias` is set by the user, while `name `is the default product name.
These requirements are due to the fact that `alias` is set by the user, while `name` is the default product name.
Of course, it's clear that writing something like this everywhere is a bad idea:

```Swift
Expand Down
4 changes: 2 additions & 2 deletions TechDocs/Nodes/Existing.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Content:
- [DTOMapperNode](#dtomappernode)
- [RequestAssembly](#requestassembly)
- [RequestCreatorNode](#requestcreatornode)
- [TechnicaErrorMapperNode](#technicaerrormappernode)
- [TechnicalErrorMapperNode](#technicalerrormappernode)
- [RequestSenderNode](#requestsendernode)
- [ResponseProcessorNode](#responseprocessornode)
- [ResponseDataPreprocessorNode](#responsedatapreprocessornode)
Expand Down Expand Up @@ -56,7 +56,7 @@ This set consists of the following nodes:

This node creates an HTTP request using URLSession and passes it along for further processing.

## TechnicaErrorMapperNode
## TechnicalErrorMapperNode

This node does nothing with the input data but transforms the output. In case the further chain ends with an error, it checks if the error is a system error (such as a timeout, lack of internet connection, etc.). If it is, it converts it into its own error and passes it along.

Expand Down
2 changes: 1 addition & 1 deletion TechDocs/Testing/NodeKitMock.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ class MyService {
func getUsers() async -> NodeResult<User> {
return await chainBuilder
.route(.get, .users)
.build<Void, User>()
.build()
.process()
}
}
Expand Down
25 changes: 12 additions & 13 deletions TechDocs/Usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,21 +9,20 @@
- [How to use Combine](#howtousecombine)

Here are the main points and additional information on how to work with this library.
The project contains an Example where several query options are written - you can look there as an interactive example.
The project contains an [Example](../Example) where several queries are written - you can look there as an interactive example.

## Creating a request <a name="creatingarequest"></a>


Sending a network request begins with describing:

1) Route - URI to the desired service
2) HTTP method - request method (GET, PUT, etc.)
3) Encoding - where to place the parameters and in what format (JSON in Body, String in Query, etc.)
4) Metadata - or request headers.
3) Encoding - where to place the parameters and specify the format (JSON in Body, String in Query, etc.)
4) Metadata - request headers

### Routing <a name="routing"></a>

To abstract the way of specifying the route (for example, in gRPC there are no explicit URLs), the route is a generic data type, however, in the case of URL requests, an UrlRouteProvider is expected.
To abstract the way of specifying the route (for example, in gRPC there are no explicit URLs), the route is a generic data type, however, in the case of URL requests, an URLRouteProvider is expected.

This approach makes working with URL addresses a bit more elegant. For example:

Expand Down Expand Up @@ -53,24 +52,24 @@ extension RegistrationRoute: UrlRouteProvider {

#### Good to know

For simplifying URL handling in CoreNetKit, there is an [extension](https://surfstudio.github.io/NodeKit/Extensions/Optional.html) for concatenating URL and String.
For simplifying URL handling in CoreNetKit, there is an [extension](../docs/Extensions/Optional.html) for concatenating URL and String.

### Encoding <a name="encoding"></a>

NodeKit provides the following encoding types:
1) `json` - serializes request parameters into JSON and attaches them to the request body. It is the default encoding.
2) `formUrl` - serializes request parameters into FormUrlEncoding format and attaches them to the request body.
2) `formUrl` - serializes request parameters into FormURLEncoding format and attaches them to the request body.
3) `urlQuery` - converts parameters into a string, replacing certain characters with special sequences (forms a URL-encoded string).

These parameters are located in [ParametersEncoding](https://surfstudio.github.io/Enums/ParametersEncoding.html)
These parameters are located in [ParametersEncoding](../docs/Enums/ParametersEncoding.html)

## Sending the request <a name="sendingtherequest"></a>

To send the request, you need to call the chain and pass it the parameters described above.

### Service <a name="service"></a>

As an example, let's write a service..
As an example, let's write a service.

```Swift
class ExampleService {
Expand Down Expand Up @@ -117,10 +116,10 @@ class ExampleService {

To execute the request, we use [chains](Chains.md).

### Response response <a name="response"></a>
### Response <a name="response"></a>

For working with the service, it is suggested to use `NodeResult<T>.` Where `NodeResult<T> = Result<T, Error>`.
You can view the available methods of NodeResult [here]("https://surfstudio.github.io/NodeKit/Extensions/NodeResult.html").
You can view the available methods of NodeResult [here](../docs/Extensions/NodeResult.html).
Let's consider how interaction with the service will look like from the presenter (or any other entity that communicates with the server).

```Swift
Expand Down Expand Up @@ -169,11 +168,11 @@ class ExampleService {
let service = ExampleService()

let subscription1 = service.getUser(by: "1")
.sink { user in // <-- New Task is created and process called
.sink { user in // <-- New Task is created and process is called
}

let subscription2 = service.getUser(by: "2")
.sink { user in // <-- New Task is created and process called
.sink { user in // <-- New Task is created and process is called
}

// Cancel the first task
Expand Down

0 comments on commit 767956f

Please sign in to comment.