Skip to content

Commit 9c9f53d

Browse files
committed
chore: add gh-pages
1 parent d849be8 commit 9c9f53d

29 files changed

+169
-57
lines changed

.github/README.md

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
1+
> [!IMPORTANT]
2+
>
3+
> Keep this file with [`index.md`](../index.md)
4+
15
# nestjs-materials
26

37
NestJS tips, tricks, Notes, Things which are not in doc and I used to figure them out and use them
48

5-
- [Microservices](./microservices/README.md)
6-
7-
# Some docs
8-
9-
- [How to debug your code and flaky tests](./docs/debugging/README.md).
10-
- [Designing and versioning RESTful APIs](./docs/designing-restful-api/README.md).
11-
- [MockServer and mocking 3rd-party HTTP/S calls](./docs/mockserver/README.md).
12-
- [Kafka intro](./docs/kafka/README.md).
13-
- [RabbitMQ intro](./docs/rabbitmq/README.md).
9+
- [Microservices](../microservices/README.md)
10+
- [How to debug your code and flaky tests](../docs/debugging/README.md).
11+
- [Designing and versioning RESTful APIs](../docs/designing-restful-api/README.md).
12+
- [Pagination](../docs/designing-restful-api/pagination.md).
13+
- [MockServer and mocking 3rd-party HTTP/S calls](../docs/mockserver/README.md).
14+
- [Kafka intro](../docs/kafka/README.md).
15+
- [RabbitMQ intro](../docs/rabbitmq/README.md).

_config.yml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
title: NestJS materials
2+
3+
description: >- # this means to ignore newlines until "baseurl:"
4+
Write an awesome doc for NestJS tips, tricks, notes, things which are not in the doc (or are but not really obvious) and experimented to figure them out and use them.
5+
baseurl: "/nestjs-materials" # the repository name
6+
url: "" # the base hostname & protocol for your site, e.g. http://example.com
7+
twitter_username: kasir_barati
8+
github_username: kasir-barati
9+
plugins:
10+
- jekyll-relative-links
11+
- jekyll-remote-theme # add this line to the plugins list if you already have one
12+
relative_links:
13+
enabled: true
14+
collections: true
15+
remote_theme: pages-themes/[email protected]
16+
kramdown:
17+
math_engine: mathjax
18+
syntax_highlighter: rouge
19+
include:
20+
- .github
File renamed without changes.
File renamed without changes.

.github/docs/designing-restful-api/README.md renamed to docs/designing-restful-api/README.md

Lines changed: 8 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
- Get feedbacks frequently on what you're building.
99
- Approach the subject from the customers perspective.
1010

11-
![Lookout for customers perspective and feedbacks](./customer-first-principle.png)
11+
![Lookout for customers perspective and feedbacks](./assets/customer-first-principle.png)
1212

1313
## Hero scenarios
1414

@@ -118,12 +118,12 @@ An endpoint is idempotent when retrying a request has the same intended affect,
118118

119119
- Dissecting an endpoint:
120120

121-
![Dissecting an endpoint](./dissecting-an-endpoint.png)
121+
![Dissecting an endpoint](./assets/dissecting-an-endpoint.png)
122122

123123
- Body: holds the resource state.
124124
- <a id="httpMethods" href="#httpMethods">#</a> HTTP methods:
125125

126-
![HTTP methods](./http-methods.png)
126+
![HTTP methods](./assets/http-methods.png)
127127

128128
## A complete example for `airports` resource.
129129

@@ -226,49 +226,9 @@ An endpoint is idempotent when retrying a request has the same intended affect,
226226
227227
**Note**: While we are paginating our resources for a specific client, another client might add or remove something. That's why it is crucial that our client is programmed robustly enough so it can handle skipped, or duplicated data.
228228
229-
We have 3 kinds of pagination:
230-
231-
1. <a href="#cursorBasedPagination" id="cursorBasedPagination">#</a> Server-driven pagination (cursor-based pagination):
232-
- This gives our server more control and can be utilized where we are serving different clients and server is not up to the task of dealing with pagination on top of other tasks it has to complete.
233-
- In the example above the `nextLink` is URL to the next page,
234-
- It can contains query strings.
235-
- It can be the ID of next element, or `offset`.
236-
- Note: It is best to keep the cursor opaque:
237-
- Cursor's internal representation or meaning is hidden and not meant to be understood or relied upon by clients..
238-
- Encode the cursor with a base64 algorithm.
239-
- No `nextField` means that we've reach the end of the road.
240-
- You can see how it is done in GraphQL [here](https://github.com/kasir-barati/graphql/tree/main/docs/best-practices/pagination.md).
241-
2. Client-driven pagination (offset-based pagination): enables our client to have a finer grasp over what is being returned. Good for when we have a very tight requirements in our client app.
242-
3. Or we can use both.
243-
244-
**Filtering, sorting, and paginating**:
245-
246-
TBF I am not sure if I have ever though this way.
247-
248-
1. Server must evaluate the filtering first (so we have applied filters).
249-
2. We need to apply `order by`s specified by client.
250-
- **Caution**: Order by is supper expensive. So you might wanna consider to not implement it.
251-
3. We can skip part of it.
252-
4. Lastly we wanna return the page that user have asked for it.
253-
254-
I am not totally sold on the idea that these SQL/MongoDB queries but nonetheless I thought it would be really helpful:
255-
256-
```sql
257-
SELECT *
258-
FROM users
259-
WHERE status = 'active'
260-
ORDER BY created_at DESC, username ASC
261-
LIMIT 10
262-
OFFSET 20;
263-
```
264-
265-
```js
266-
db.collection("users")
267-
.find({ status: "active" })
268-
.sort({ created_at: -1, username: 1 })
269-
.skip(20)
270-
.limit(10);
271-
```
229+
> [!IMPORTANT]
230+
>
231+
> Learn more about pagination [here](./pagination.md).
272232
273233
**Delete**
274234
@@ -545,7 +505,7 @@ Up until now we've kinda briefly touched this topic for the response body:
545505
- Identify resources through an immutable and stable identity.
546506
- E.g. you can have a slug for your posts, or a username for user but these ain't the identifier of those resources. Take a look at Stackoverflow. We have slugs in the browser's address bar. But when I click on the share button it will gimme a unique identifier for that answer or question.
547507
548-
![Stackoverflow share button and unique identifier](./stackoverflow.png)
508+
![Stackoverflow share button and unique identifier](./assets/stackoverflow.png)
549509
550510
- <a id="applicationMergePatchJson" href="#applicationMergePatchJson">#</a> Update a resource with `application/merge-patch+json`:
551511
@@ -657,7 +617,7 @@ If they match, it means the resource has not changed, and the server can respond
657617
- `POST` according to HTTP spec does not need to be idempotent but in cloud env we have to make it idempotent.
658618
- You do not wanna charge customer for the same thing twice, right?
659619
660-
![POST HTTP method](./post-http-method.png)
620+
![POST HTTP method](./assets/post-http-method.png)
661621
662622
# Throttling client request
663623
Loading
Loading
Loading
Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Pagination
2+
3+
- Glossed over in introductory tutorials.
4+
- A philosophical question: "why we need tp paginate our data set?"
5+
- UX concern: too many items to display.
6+
- Can be solved in frontend.
7+
- Performance concern: too many items to load.
8+
- Needs our backend to be involved.
9+
- What we will talk about here.
10+
11+
> [!IMPORTANT]
12+
>
13+
> Here I did not go into details about pagination in SQL and what kind of issues you need to be aware of in SQL since I have written an extensive comprehensible doc [here](https://github.com/kasir-barati/sql/blob/main/.github/docs/select/pagination.md) for it.
14+
15+
## Pagination from a user's perspective
16+
17+
- Numbered pagination:
18+
19+
![Google pagination UX](./assets/google-pagination-ux.png)
20+
21+
- Something stays in a page for a certain amount of time usually.
22+
- Easiest tom implement with technologies we have:
23+
- Easy to query data.
24+
- Maps easily on to REST and GraphQL.
25+
26+
- Sequential pagination:
27+
28+
![Reddit pagination UX](./assets/reddit-pagination-ux.png)
29+
30+
- New pages will be added too fast, thus it does not make sense to number them.
31+
- Most common.
32+
33+
- Infinite scroll pagination:
34+
35+
![LinkedIn pagination UX](./assets/linkedin-pagination-ux.png)
36+
37+
- Feeds.
38+
- Page is not important.
39+
- Scroll to get more info.
40+
- Most common.
41+
42+
## 3 kinds of pagination from a technical point of view
43+
44+
1. <a href="#cursorBasedPagination" id="cursorBasedPagination">#</a> Server-driven pagination (cursor-based pagination):
45+
- This gives our server more control and can be utilized where we are serving different clients and server is not up to the task of dealing with pagination on top of other tasks it has to complete.
46+
- In the example above the `nextLink` is URL to the next page,
47+
- It can contains query strings.
48+
- It can be the ID of next element, or `offset`.
49+
- Note: It is best to keep the cursor opaque:
50+
- Cursor's internal representation or meaning is hidden and not meant to be understood or relied upon by clients..
51+
- Encode the cursor with a base64 algorithm.
52+
- No `nextField` means that we've reach the end of the road.
53+
- You can see how it is done in GraphQL [here](https://github.com/kasir-barati/graphql/tree/main/docs/best-practices/pagination.md).
54+
2. Client-driven pagination (offset-based pagination): enables our client to have a finer grasp over what is being returned. Good for when we have a very tight requirements in our client app.
55+
3. Or we can use both.
56+
57+
### Numbered pagination (`OFFSET` & `LIMIT`)
58+
59+
**Filtering, sorting, and paginating**:
60+
61+
1. Server must evaluate the filtering first (so we have applied filters).
62+
2. We need to apply `order by`s specified by client.
63+
- **Caution**: Order by is supper expensive. So you might wanna consider to not implement it.
64+
3. We can skip part of it.
65+
- **Caution**: It's easy to skipping an item.
66+
- **Caution**: It's easy to display same data twice!
67+
4. Lastly we wanna return the page that user have asked for it.
68+
69+
I am not totally sold on the idea that these SQL/MongoDB queries but nonetheless I thought it would be really helpful:
70+
71+
```sql
72+
// users
73+
SELECT *
74+
FROM users
75+
WHERE status = 'active'
76+
ORDER BY created_at DESC, username ASC
77+
LIMIT 10
78+
OFFSET 20;
79+
80+
# total
81+
SELECT COUNT(*)
82+
FROM users
83+
WHERE status = 'active';
84+
```
85+
86+
```js
87+
db.collection("users")
88+
.find({ status: "active" })
89+
.sort({ created_at: -1, username: 1 })
90+
.skip(20)
91+
.limit(10);
92+
```
93+
94+
```http
95+
GET https://meta.discourse.org/latest.json?page=2
96+
```
97+
98+
Page info:
99+
100+
- Page number: 3. Thus starting after item 20
101+
- Page size/limit: 10.
102+
103+
### Cursor-based pagination
104+
105+
- We just specify the place in the list we want to begin, and then how many items we want to fetch?
106+
- We have a constant pointer to the specific spot where we left off. This pointer is called a cursor.
107+
108+
```http
109+
https://www.reddit.com/
110+
https://www.reddit.com/?count=25&after=t3_49i88b
111+
```
112+
113+
Again read [this doc](https://github.com/kasir-barati/sql/blob/main/.github/docs/select/pagination.md) for an in-depth explanation.
114+
115+
### Relay pagination
116+
117+
For this you can learn more [here](https://github.com/kasir-barati/graphql/blob/main/docs/best-practices/pagination.md).
118+
119+
## Ref
120+
121+
- [Understanding pagination: REST, GraphQL, and Relay](https://www.apollographql.com/blog/understanding-pagination-rest-graphql-and-relay).
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

index.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Table of contents
2+
3+
- [Microservices](./microservices/README.md)
4+
- [How to debug your code and flaky tests](../docs/debugging/README.md).
5+
- [Designing and versioning RESTful APIs](../docs/designing-restful-api/README.md).
6+
- [Pagination](./docs/designing-restful-api/pagination.md).
7+
- [MockServer and mocking 3rd-party HTTP/S calls](../docs/mockserver/README.md).
8+
- [Kafka intro](../docs/kafka/README.md).
9+
- [RabbitMQ intro](../docs/rabbitmq/README.md).

0 commit comments

Comments
 (0)