From 91fb1376b4112a3455fb68d8d78a001ec530fbfa Mon Sep 17 00:00:00 2001 From: Vegard Kyrkjedelen Hovland Date: Sat, 15 Mar 2025 22:03:53 +0100 Subject: [PATCH 1/5] docs: :memo: Added backend documentation Including: zod, express, drizzle, testing and documentation --- backend/README.md | 7 ++++ backend/learn-api-documentation.md | 60 +++++++++++++++++++++++++++++ backend/learn-backend-testing.md | 32 +++++++++++++++ backend/learn-drizzle.md | 55 ++++++++++++++++++++++++++ backend/learn-express.md | 62 ++++++++++++++++++++++++++++++ backend/learn-zod.md | 42 ++++++++++++++++++++ code-style.md | 6 ++- 7 files changed, 263 insertions(+), 1 deletion(-) create mode 100644 backend/README.md create mode 100644 backend/learn-api-documentation.md create mode 100644 backend/learn-backend-testing.md create mode 100644 backend/learn-drizzle.md create mode 100644 backend/learn-express.md create mode 100644 backend/learn-zod.md diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..f13cf3c --- /dev/null +++ b/backend/README.md @@ -0,0 +1,7 @@ +# back end + +- [Learn Express](learn-express.md) +- [Learn Zod](learn-zod.md) +- [Learn Drizzle](learn-drizzle.md) +- [Learn Backend Testing](learn-backend-testing.md) +- [Learn API documentation](learn-api-documentation.md) diff --git a/backend/learn-api-documentation.md b/backend/learn-api-documentation.md new file mode 100644 index 0000000..1a83405 --- /dev/null +++ b/backend/learn-api-documentation.md @@ -0,0 +1,60 @@ +# Learn API documentation + +## Table of contents + +- [Learn API documentation](#learn-api-documentation) + - [Table of contents](#table-of-contents) + - [Tools](#tools) + - [Swagger](#swagger) + - [ZodOpenAPI](#zodopenapi) + - [How to add OpenAPI specifications](#how-to-add-openapi-specifications) + - [How to add a resource to the specification](#how-to-add-a-resource-to-the-specification) + - [How to add a scema to the specification](#how-to-add-a-scema-to-the-specification) + +## Tools + +### [Swagger](https://swagger.io/docs/specification/v3_0/about/) + +Swagger is a set tools that easier to follow the OpenAPI specification. +We use the swagger-ui-express tool to host our openapi specification in our api itself. +We use th swagger-jsdoc tool to write openapi specifications in jsdoc comments directly in the code, to make the specifications easier to write and read, when you can look at the code in the same place. + +### [ZodOpenAPI](https://www.npmjs.com/package/zod-openapi) + +A tool used to transform our Zod scemas to schemas we can use in our OpenAPI specification. + +## How to add OpenAPI specifications + +### How to add a resource to the specification + +To add an addition to the OpenAPI specification, you need to add a comment following this format: + +```yaml +/** + * @openapi + * /path/to/your/resource: + * (http verb here): + * tags: [some, tags, in, here] + * summary: "Here goes the summary" + * description: "And here the description" + * parameters: + * - $ref: "#/components/parameters/yourParameterHere" + * requestBody: + * required: true + * content: + * json: + * schema: + * $ref: "#/components/schemas/yourRequestScema" + * responses: + * (response code here): + * description: "Description of your response + * content: + * application/json: + * schema: + * $ref: "#/components/schemas/yourReturnScema" + */ +``` + +### How to add a scema to the specification + +In order to add a Zod schema to the OpenAPI specification, go to [the openapi configuration file](https://github.com/vektorprogrammet/api/blob/main/src/openapi/config.ts). Under components you can add your schema. Remember that when you reference you scema in the specification, use the key assigned it with here. diff --git a/backend/learn-backend-testing.md b/backend/learn-backend-testing.md new file mode 100644 index 0000000..4743311 --- /dev/null +++ b/backend/learn-backend-testing.md @@ -0,0 +1,32 @@ +# Backend testing tutorial + +## Table of contents + +- [Backend testing tutorial](#backend-testing-tutorial) + - [Table of contents](#table-of-contents) + - [Tools](#tools) + - [Node testrunner](#node-testrunner) + - [Node assert](#node-assert) + - [Supertest](#supertest) + - [Insomnia](#insomnia) + +## Tools + +### [Node testrunner](https://nodejs.org/docs/latest-v22.x/api/test.html) + +Node testrunner is a built in node module we use to run tests with. It is important that you verify thar you use node version 22 or higher, in order to make this module work as expected. + +### [Node assert](https://nodejs.org/docs/latest-v22.x/api/assert.html) + +Node assert is a built in node library containing a set of functions for verifying correctedness in tests. + +### [Supertest](https://www.npmjs.com/package/supertest) + +Supertest is a HTTP testing tool, built on Superagent. We use it to run different HTTP requests to our API in order to check that it returns the correct responses. + +### [Insomnia](https://insomnia.rest/) + +Insomnia is an open source desktop application used for interacting with and designing, debugging, and testing APIs. We use it to usertest that specific requests works as expected. + +Official documentation: +Download page: diff --git a/backend/learn-drizzle.md b/backend/learn-drizzle.md new file mode 100644 index 0000000..a97aa70 --- /dev/null +++ b/backend/learn-drizzle.md @@ -0,0 +1,55 @@ +# Learn Drizzle + +## Table of contents + +- [Learn Drizzle](#learn-drizzle) + - [Table of contents](#table-of-contents) + - [What is Drizzle?](#what-is-drizzle) + - [Drizzle ORM](#drizzle-orm) + - [Drizzle Kit](#drizzle-kit) + - [Drizzle Seed](#drizzle-seed) + - [Why Drizzle?](#why-drizzle) + - [How we use Drizzle](#how-we-use-drizzle) + - [Drizzle learning resources](#drizzle-learning-resources) + +## What is Drizzle? + +Drizzle ORM is a collection of database management and access tools. The most promintent one is Drizzle ORM. But there is also Drizzle Kit and Drizzle Seed. + +### Drizzle ORM + +Drizzle ORM is a object relational mapper (ORM) and is used to define and manage database schemas, and also allows you to acces the data in a SQL-like or relational way. + +### Drizzle Kit + +Drizzle Kit is a tool used to generate and run SQL migration files. It also comes with Drizzle Studio, a database visualising and interaction tool. + +### Drizzle Seed + +Drizzle Seed is a TypeScript library that helps you generate deterministic, yet realistic, fake data to populate your database. By leveraging a seedable pseudorandom number generator (pRNG), it ensures that the data you generate is consistent and reproducible across different runs. + +## Why Drizzle? + +We use drizzle because it gives us easy definitions of tables in our database, but doesn't abstract too much away from the actual database. There is also a lot of good tools to make Drizzle fit with our other tools. + +## How we use Drizzle + +Drizzle is used all all over the place: + +- table declaration ([db/tables](https://github.com/vektorprogrammet/api/tree/main/db/tables)) +- database migration ([db/config](https://github.com/vektorprogrammet/api/blob/main/db/config/drizzle.config.ts)) +- database access ([src/db-access](https://github.com/vektorprogrammet/api/blob/main/src/db-access)) + +## Drizzle learning resources + +Drizzle ORM in 100 seconds: +Intro video to Drizzle: +Drizzle Guides for common task: + +Official documentation: +Officail sourcecode: +NPM packages: + +- ORM: +- kit: +- seed: diff --git a/backend/learn-express.md b/backend/learn-express.md new file mode 100644 index 0000000..b8c67e2 --- /dev/null +++ b/backend/learn-express.md @@ -0,0 +1,62 @@ +# Learn Express + +- [Learn Express](#learn-express) + - [What is express?](#what-is-express) + - [What are RESTful APIs?](#what-are-restful-apis) + - [What are HTTP requests?](#what-are-http-requests) + - [Why express?](#why-express) + - [How we use express](#how-we-use-express) + - [Express learning resources](#express-learning-resources) + +## What is express? + +Express is a back end web application framework for building RESTful APIs with Node.js. + +### What are RESTful APIs? + +REST(REpresentational State Transfer) is a architecture style describing how a multimedia system exposed to the internet should behave. + +A core principle in REST is that the client and server don't need to know what state the other is in. This makes it easier to create reliable interfaces over the web. + +A RESTful api requires the client to send HTTP-requests to the server + +### What are HTTP requests? + +Http requests consists of: + +- a path to a resource +- an HTTP verb, which defines what kind of operation to perform +- a header, which allows the client to pass along information about the request +- an optional message body containing data + +There are four basic HTTP request verbs: GET, POST, PUT and delete. These corresponds to the four CRUD operations + +Read more about the CRUD operations on Wikipedia: + + + +## Why express? + +We use express because it is one of the most vidley used web application frameworks both in node and in general. It is easy to use and has a good amount of both official documentation and tutorials all availible online. + +## How we use express + +We use express to listen for requests to our server from the frontend. See: + +- [src/main](https://github.com/vektorprogrammet/api/blob/main/src/main.ts) +- [src/routes](https://github.com/vektorprogrammet/api/tree/main/src/routers) + +## Express learning resources + +RESTful APIs in 100 seconds: +HTTP request methods: + +Wikipedia: + +- english: +- norwegian: + +Official documentation: +Official sourcecode: +Official wiki: +NPM package: diff --git a/backend/learn-zod.md b/backend/learn-zod.md new file mode 100644 index 0000000..467eabd --- /dev/null +++ b/backend/learn-zod.md @@ -0,0 +1,42 @@ +# Learn Zod + +## Table of contents + +- [Learn Zod](#learn-zod) + - [Table of contents](#table-of-contents) + - [What is Zod?](#what-is-zod) + - [Why zod?](#why-zod) + - [How we use Zod](#how-we-use-zod) + - [Zod learning resources](#zod-learning-resources) + +## What is Zod? + +Zod is a schema declaration and validation library. The term "schema" broadly refers to any data type, from a simple string to a complex nested object. + +## Why zod? + +Typescript has a powerful and complex type system. This fact might make you wonder why we would need Zod to validate our literals and objects. +Well, the fact is also that while Typescript has a powerful typesystem, it is built upon a language with no types. This often makes it hard to verify types at runtime, either because they originate from a pure-javascript module, or if your object is parsed from a string or similar. +Zod therefore introduces features for parsing objects and literals at runtime. This is incredibly usefull, becuase writing such code on your own can get incredibly convoluted. + +To read more about the motivation for zod and other zod alternatives, see this blockpost by the creator: + +## How we use Zod + +We use zod to parse: + +- API requests (see [src/requestparsing](https://github.com/vektorprogrammet/api/tree/main/src/response-handling)) + - url queries + - parameters + - json bodies +- database errors (see [db/errors](https://github.com/vektorprogrammet/api/tree/main/db/errors)) +- enviromentvariables (see [src/enviroment](https://github.com/vektorprogrammet/api/blob/main/src/enviroment.ts) or [db/config/parameters](https://github.com/vektorprogrammet/api/blob/main/db/config/parameters.ts)) + +## Zod learning resources + +Intro video to Zod: +Some zod exersises: + +Official documentation: +Official sourcekode: +NPM package: diff --git a/code-style.md b/code-style.md index efef7e8..b43f2ea 100644 --- a/code-style.md +++ b/code-style.md @@ -14,6 +14,7 @@ VektorIT's code style which cannot be enforced using linters or formatters. - [TypeScript](#typescript) - [Write pure functions when possible](#write-pure-functions-when-possible) - [Avoid explicit type declaration when types can be inferred](#avoid-explicit-type-declaration-when-types-can-be-inferred) + - [This is not the case for back end code](#this-is-not-the-case-for-back-end-code) - [Variable names are camelCase](#variable-names-are-camelcase) - [Type names are PascalCase](#type-names-are-pascalcase) - [React](#react) @@ -149,6 +150,10 @@ add(2, 5); } ``` +#### This is not the case for back end code + +In the backend it is more important that types stay consistant. It is also harder to figure out exactly what returntype of a function is just by glancing at it. Therefore please try to explisitly type your functions when writing backend code. + ### Variable names are camelCase By JavaScript convention. @@ -189,7 +194,6 @@ Make sure you understand that functions in JavaScript are [hoisted](https://deve } ``` - ### ReactNode or ReactElement? From e3bc2efef753fbfeb86fb3e0ead994b15ae29153 Mon Sep 17 00:00:00 2001 From: Vegard Kyrkjedelen Hovland Date: Sun, 16 Mar 2025 11:50:15 +0100 Subject: [PATCH 2/5] docs: :memo: Fix requested changes --- backend/README.md | 2 +- backend/learn-backend-testing.md | 2 +- backend/learn-express.md | 12 ++++++------ backend/learn-zod.md | 4 ++-- code-style.md | 5 ----- 5 files changed, 10 insertions(+), 15 deletions(-) diff --git a/backend/README.md b/backend/README.md index f13cf3c..2f57ab5 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,4 +1,4 @@ -# back end +# Backend - [Learn Express](learn-express.md) - [Learn Zod](learn-zod.md) diff --git a/backend/learn-backend-testing.md b/backend/learn-backend-testing.md index 4743311..5a0e9c1 100644 --- a/backend/learn-backend-testing.md +++ b/backend/learn-backend-testing.md @@ -14,7 +14,7 @@ ### [Node testrunner](https://nodejs.org/docs/latest-v22.x/api/test.html) -Node testrunner is a built in node module we use to run tests with. It is important that you verify thar you use node version 22 or higher, in order to make this module work as expected. +Node testrunner is a built in Node module we use to run tests with. It is important that you verify thar you use node version 22 or higher, in order to make this module work as expected. ### [Node assert](https://nodejs.org/docs/latest-v22.x/api/assert.html) diff --git a/backend/learn-express.md b/backend/learn-express.md index b8c67e2..141b187 100644 --- a/backend/learn-express.md +++ b/backend/learn-express.md @@ -1,14 +1,14 @@ # Learn Express - [Learn Express](#learn-express) - - [What is express?](#what-is-express) + - [What is Express?](#what-is-express) - [What are RESTful APIs?](#what-are-restful-apis) - [What are HTTP requests?](#what-are-http-requests) - - [Why express?](#why-express) - - [How we use express](#how-we-use-express) + - [Why Express?](#why-express) + - [How we use Express](#how-we-use-express) - [Express learning resources](#express-learning-resources) -## What is express? +## What is Express? Express is a back end web application framework for building RESTful APIs with Node.js. @@ -35,11 +35,11 @@ Read more about the CRUD operations on Wikipedia: -## Why express? +## Why Express? We use express because it is one of the most vidley used web application frameworks both in node and in general. It is easy to use and has a good amount of both official documentation and tutorials all availible online. -## How we use express +## How we use Express We use express to listen for requests to our server from the frontend. See: diff --git a/backend/learn-zod.md b/backend/learn-zod.md index 467eabd..cfb1e60 100644 --- a/backend/learn-zod.md +++ b/backend/learn-zod.md @@ -35,8 +35,8 @@ We use zod to parse: ## Zod learning resources Intro video to Zod: -Some zod exersises: +Some Zod exercises: Official documentation: -Official sourcekode: +Official source code: NPM package: diff --git a/code-style.md b/code-style.md index b43f2ea..3579d76 100644 --- a/code-style.md +++ b/code-style.md @@ -14,7 +14,6 @@ VektorIT's code style which cannot be enforced using linters or formatters. - [TypeScript](#typescript) - [Write pure functions when possible](#write-pure-functions-when-possible) - [Avoid explicit type declaration when types can be inferred](#avoid-explicit-type-declaration-when-types-can-be-inferred) - - [This is not the case for back end code](#this-is-not-the-case-for-back-end-code) - [Variable names are camelCase](#variable-names-are-camelcase) - [Type names are PascalCase](#type-names-are-pascalcase) - [React](#react) @@ -150,10 +149,6 @@ add(2, 5); } ``` -#### This is not the case for back end code - -In the backend it is more important that types stay consistant. It is also harder to figure out exactly what returntype of a function is just by glancing at it. Therefore please try to explisitly type your functions when writing backend code. - ### Variable names are camelCase By JavaScript convention. From d6dd945e4be81b4f29cc0d36e9f893afc050f211 Mon Sep 17 00:00:00 2001 From: Vegard Kyrkjedelen Hovland Date: Sun, 16 Mar 2025 11:58:05 +0100 Subject: [PATCH 3/5] docs: :memo: Fix typo in learn-api-docs --- backend/learn-api-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backend/learn-api-documentation.md b/backend/learn-api-documentation.md index 1a83405..dea5d54 100644 --- a/backend/learn-api-documentation.md +++ b/backend/learn-api-documentation.md @@ -17,7 +17,7 @@ Swagger is a set tools that easier to follow the OpenAPI specification. We use the swagger-ui-express tool to host our openapi specification in our api itself. -We use th swagger-jsdoc tool to write openapi specifications in jsdoc comments directly in the code, to make the specifications easier to write and read, when you can look at the code in the same place. +We use the swagger-jsdoc NPM package to write openapi specifications in jsdoc comments directly in the code, to make the specifications easier to write and read, when you can look at the code in the same place. ### [ZodOpenAPI](https://www.npmjs.com/package/zod-openapi) From 78c6101099da3d83d16b07ccd42613d9fd4d38c1 Mon Sep 17 00:00:00 2001 From: Vegard Kyrkjedelen Hovland Date: Sun, 16 Mar 2025 12:06:59 +0100 Subject: [PATCH 4/5] docs: :memo: Make all sentences have its own line --- backend/learn-api-documentation.md | 3 ++- backend/learn-backend-testing.md | 8 +++++--- backend/learn-drizzle.md | 17 +++++++++++++---- backend/learn-express.md | 20 ++++++++++++++------ backend/learn-zod.md | 20 +++++++++++++------- 5 files changed, 47 insertions(+), 21 deletions(-) diff --git a/backend/learn-api-documentation.md b/backend/learn-api-documentation.md index dea5d54..e2e8985 100644 --- a/backend/learn-api-documentation.md +++ b/backend/learn-api-documentation.md @@ -57,4 +57,5 @@ To add an addition to the OpenAPI specification, you need to add a comment follo ### How to add a scema to the specification -In order to add a Zod schema to the OpenAPI specification, go to [the openapi configuration file](https://github.com/vektorprogrammet/api/blob/main/src/openapi/config.ts). Under components you can add your schema. Remember that when you reference you scema in the specification, use the key assigned it with here. +In order to add a Zod schema to the OpenAPI specification, go to [the openapi configuration file](https://github.com/vektorprogrammet/api/blob/main/src/openapi/config.ts). +Under components you can add your schema. Remember that when you reference you scema in the specification, use the key assigned it with here. diff --git a/backend/learn-backend-testing.md b/backend/learn-backend-testing.md index 5a0e9c1..b23565f 100644 --- a/backend/learn-backend-testing.md +++ b/backend/learn-backend-testing.md @@ -14,15 +14,17 @@ ### [Node testrunner](https://nodejs.org/docs/latest-v22.x/api/test.html) -Node testrunner is a built in Node module we use to run tests with. It is important that you verify thar you use node version 22 or higher, in order to make this module work as expected. +Node testrunner is a built in Node module we use to run tests with. +It is important that you verify thar you use Node version 22 or higher, in order to make this module work as expected. ### [Node assert](https://nodejs.org/docs/latest-v22.x/api/assert.html) -Node assert is a built in node library containing a set of functions for verifying correctedness in tests. +Node assert is a built in Node library containing a set of functions for verifying correctedness in tests. ### [Supertest](https://www.npmjs.com/package/supertest) -Supertest is a HTTP testing tool, built on Superagent. We use it to run different HTTP requests to our API in order to check that it returns the correct responses. +Supertest is a HTTP testing tool, built on Superagent. +We use it to run different HTTP requests to our API in order to check that it returns the correct responses. ### [Insomnia](https://insomnia.rest/) diff --git a/backend/learn-drizzle.md b/backend/learn-drizzle.md index a97aa70..6ffbdf8 100644 --- a/backend/learn-drizzle.md +++ b/backend/learn-drizzle.md @@ -14,7 +14,9 @@ ## What is Drizzle? -Drizzle ORM is a collection of database management and access tools. The most promintent one is Drizzle ORM. But there is also Drizzle Kit and Drizzle Seed. +Drizzle ORM is a collection of database management and access tools. +The most promintent one is Drizzle ORM. +But there is also Drizzle Kit and Drizzle Seed. ### Drizzle ORM @@ -22,15 +24,18 @@ Drizzle ORM is a object relational mapper (ORM) and is used to define and manage ### Drizzle Kit -Drizzle Kit is a tool used to generate and run SQL migration files. It also comes with Drizzle Studio, a database visualising and interaction tool. +Drizzle Kit is a tool used to generate and run SQL migration files. +It also comes with Drizzle Studio, a database visualising and interaction tool. ### Drizzle Seed -Drizzle Seed is a TypeScript library that helps you generate deterministic, yet realistic, fake data to populate your database. By leveraging a seedable pseudorandom number generator (pRNG), it ensures that the data you generate is consistent and reproducible across different runs. +Drizzle Seed is a TypeScript library that helps you generate deterministic, yet realistic, fake data to populate your database. +By leveraging a seedable pseudorandom number generator (pRNG), it ensures that the data you generate is consistent and reproducible across different runs. ## Why Drizzle? -We use drizzle because it gives us easy definitions of tables in our database, but doesn't abstract too much away from the actual database. There is also a lot of good tools to make Drizzle fit with our other tools. +We use drizzle because it gives us easy definitions of tables in our database, but doesn't abstract too much away from the actual database. +There is also a lot of good tools to make Drizzle fit with our other tools. ## How we use Drizzle @@ -43,11 +48,15 @@ Drizzle is used all all over the place: ## Drizzle learning resources Drizzle ORM in 100 seconds: + Intro video to Drizzle: + Drizzle Guides for common task: Official documentation: + Officail sourcecode: + NPM packages: - ORM: diff --git a/backend/learn-express.md b/backend/learn-express.md index 141b187..7ecca12 100644 --- a/backend/learn-express.md +++ b/backend/learn-express.md @@ -16,7 +16,8 @@ Express is a back end web application framework for building RESTful APIs with N REST(REpresentational State Transfer) is a architecture style describing how a multimedia system exposed to the internet should behave. -A core principle in REST is that the client and server don't need to know what state the other is in. This makes it easier to create reliable interfaces over the web. +A core principle in REST is that the client and server don't need to know what state the other is in. +This makes it easier to create reliable interfaces over the web. A RESTful api requires the client to send HTTP-requests to the server @@ -29,19 +30,22 @@ Http requests consists of: - a header, which allows the client to pass along information about the request - an optional message body containing data -There are four basic HTTP request verbs: GET, POST, PUT and delete. These corresponds to the four CRUD operations +There are four basic HTTP request verbs: GET, POST, PUT and delete. +These corresponds to the four CRUD operations Read more about the CRUD operations on Wikipedia: - - + +- +- ## Why Express? -We use express because it is one of the most vidley used web application frameworks both in node and in general. It is easy to use and has a good amount of both official documentation and tutorials all availible online. +We use Express because it is one of the most vidley used web application frameworks both in Node and in general. +It is easy to use and has a good amount of both official documentation and tutorials all availible online. ## How we use Express -We use express to listen for requests to our server from the frontend. See: +We use Express to listen for requests to our server from the frontend. See: - [src/main](https://github.com/vektorprogrammet/api/blob/main/src/main.ts) - [src/routes](https://github.com/vektorprogrammet/api/tree/main/src/routers) @@ -49,6 +53,7 @@ We use express to listen for requests to our server from the frontend. See: ## Express learning resources RESTful APIs in 100 seconds: + HTTP request methods: Wikipedia: @@ -57,6 +62,9 @@ Wikipedia: - norwegian: Official documentation: + Official sourcecode: + Official wiki: + NPM package: diff --git a/backend/learn-zod.md b/backend/learn-zod.md index cfb1e60..d489909 100644 --- a/backend/learn-zod.md +++ b/backend/learn-zod.md @@ -5,25 +5,28 @@ - [Learn Zod](#learn-zod) - [Table of contents](#table-of-contents) - [What is Zod?](#what-is-zod) - - [Why zod?](#why-zod) + - [Why Zod?](#why-zod) - [How we use Zod](#how-we-use-zod) - [Zod learning resources](#zod-learning-resources) ## What is Zod? -Zod is a schema declaration and validation library. The term "schema" broadly refers to any data type, from a simple string to a complex nested object. +Zod is a schema declaration and validation library. +The term "schema" broadly refers to any data type, from a simple string to a complex nested object. -## Why zod? +## Why Zod? -Typescript has a powerful and complex type system. This fact might make you wonder why we would need Zod to validate our literals and objects. +Typescript has a powerful and complex type system. +This fact might make you wonder why we would need Zod to validate our literals and objects. Well, the fact is also that while Typescript has a powerful typesystem, it is built upon a language with no types. This often makes it hard to verify types at runtime, either because they originate from a pure-javascript module, or if your object is parsed from a string or similar. -Zod therefore introduces features for parsing objects and literals at runtime. This is incredibly usefull, becuase writing such code on your own can get incredibly convoluted. +Zod therefore introduces features for parsing objects and literals at runtime. +This is incredibly usefull, becuase writing such code on your own can get incredibly convoluted. -To read more about the motivation for zod and other zod alternatives, see this blockpost by the creator: +To read more about the motivation for Zod and other Zod alternatives, see this blockpost by the creator: ## How we use Zod -We use zod to parse: +We use Zod to parse: - API requests (see [src/requestparsing](https://github.com/vektorprogrammet/api/tree/main/src/response-handling)) - url queries @@ -35,8 +38,11 @@ We use zod to parse: ## Zod learning resources Intro video to Zod: + Some Zod exercises: Official documentation: + Official source code: + NPM package: From 68e00650a72bc4623a63d51d7baba4db9db88d57 Mon Sep 17 00:00:00 2001 From: phibkro <71797726+phibkro@users.noreply.github.com> Date: Sun, 16 Mar 2025 17:49:41 +0100 Subject: [PATCH 5/5] docs: :memo: aggregate backend resources in 1 file --- backend/README.md | 7 - backend/learn-api-documentation.md | 61 ------- backend/learn-backend-testing.md | 34 ---- backend/learn-drizzle.md | 64 ------- backend/learn-express.md | 70 -------- backend/learn-zod.md | 48 ------ learn-backend.md | 261 +++++++++++++++++++++++++++++ 7 files changed, 261 insertions(+), 284 deletions(-) delete mode 100644 backend/README.md delete mode 100644 backend/learn-api-documentation.md delete mode 100644 backend/learn-backend-testing.md delete mode 100644 backend/learn-drizzle.md delete mode 100644 backend/learn-express.md delete mode 100644 backend/learn-zod.md create mode 100644 learn-backend.md diff --git a/backend/README.md b/backend/README.md deleted file mode 100644 index 2f57ab5..0000000 --- a/backend/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Backend - -- [Learn Express](learn-express.md) -- [Learn Zod](learn-zod.md) -- [Learn Drizzle](learn-drizzle.md) -- [Learn Backend Testing](learn-backend-testing.md) -- [Learn API documentation](learn-api-documentation.md) diff --git a/backend/learn-api-documentation.md b/backend/learn-api-documentation.md deleted file mode 100644 index e2e8985..0000000 --- a/backend/learn-api-documentation.md +++ /dev/null @@ -1,61 +0,0 @@ -# Learn API documentation - -## Table of contents - -- [Learn API documentation](#learn-api-documentation) - - [Table of contents](#table-of-contents) - - [Tools](#tools) - - [Swagger](#swagger) - - [ZodOpenAPI](#zodopenapi) - - [How to add OpenAPI specifications](#how-to-add-openapi-specifications) - - [How to add a resource to the specification](#how-to-add-a-resource-to-the-specification) - - [How to add a scema to the specification](#how-to-add-a-scema-to-the-specification) - -## Tools - -### [Swagger](https://swagger.io/docs/specification/v3_0/about/) - -Swagger is a set tools that easier to follow the OpenAPI specification. -We use the swagger-ui-express tool to host our openapi specification in our api itself. -We use the swagger-jsdoc NPM package to write openapi specifications in jsdoc comments directly in the code, to make the specifications easier to write and read, when you can look at the code in the same place. - -### [ZodOpenAPI](https://www.npmjs.com/package/zod-openapi) - -A tool used to transform our Zod scemas to schemas we can use in our OpenAPI specification. - -## How to add OpenAPI specifications - -### How to add a resource to the specification - -To add an addition to the OpenAPI specification, you need to add a comment following this format: - -```yaml -/** - * @openapi - * /path/to/your/resource: - * (http verb here): - * tags: [some, tags, in, here] - * summary: "Here goes the summary" - * description: "And here the description" - * parameters: - * - $ref: "#/components/parameters/yourParameterHere" - * requestBody: - * required: true - * content: - * json: - * schema: - * $ref: "#/components/schemas/yourRequestScema" - * responses: - * (response code here): - * description: "Description of your response - * content: - * application/json: - * schema: - * $ref: "#/components/schemas/yourReturnScema" - */ -``` - -### How to add a scema to the specification - -In order to add a Zod schema to the OpenAPI specification, go to [the openapi configuration file](https://github.com/vektorprogrammet/api/blob/main/src/openapi/config.ts). -Under components you can add your schema. Remember that when you reference you scema in the specification, use the key assigned it with here. diff --git a/backend/learn-backend-testing.md b/backend/learn-backend-testing.md deleted file mode 100644 index b23565f..0000000 --- a/backend/learn-backend-testing.md +++ /dev/null @@ -1,34 +0,0 @@ -# Backend testing tutorial - -## Table of contents - -- [Backend testing tutorial](#backend-testing-tutorial) - - [Table of contents](#table-of-contents) - - [Tools](#tools) - - [Node testrunner](#node-testrunner) - - [Node assert](#node-assert) - - [Supertest](#supertest) - - [Insomnia](#insomnia) - -## Tools - -### [Node testrunner](https://nodejs.org/docs/latest-v22.x/api/test.html) - -Node testrunner is a built in Node module we use to run tests with. -It is important that you verify thar you use Node version 22 or higher, in order to make this module work as expected. - -### [Node assert](https://nodejs.org/docs/latest-v22.x/api/assert.html) - -Node assert is a built in Node library containing a set of functions for verifying correctedness in tests. - -### [Supertest](https://www.npmjs.com/package/supertest) - -Supertest is a HTTP testing tool, built on Superagent. -We use it to run different HTTP requests to our API in order to check that it returns the correct responses. - -### [Insomnia](https://insomnia.rest/) - -Insomnia is an open source desktop application used for interacting with and designing, debugging, and testing APIs. We use it to usertest that specific requests works as expected. - -Official documentation: -Download page: diff --git a/backend/learn-drizzle.md b/backend/learn-drizzle.md deleted file mode 100644 index 6ffbdf8..0000000 --- a/backend/learn-drizzle.md +++ /dev/null @@ -1,64 +0,0 @@ -# Learn Drizzle - -## Table of contents - -- [Learn Drizzle](#learn-drizzle) - - [Table of contents](#table-of-contents) - - [What is Drizzle?](#what-is-drizzle) - - [Drizzle ORM](#drizzle-orm) - - [Drizzle Kit](#drizzle-kit) - - [Drizzle Seed](#drizzle-seed) - - [Why Drizzle?](#why-drizzle) - - [How we use Drizzle](#how-we-use-drizzle) - - [Drizzle learning resources](#drizzle-learning-resources) - -## What is Drizzle? - -Drizzle ORM is a collection of database management and access tools. -The most promintent one is Drizzle ORM. -But there is also Drizzle Kit and Drizzle Seed. - -### Drizzle ORM - -Drizzle ORM is a object relational mapper (ORM) and is used to define and manage database schemas, and also allows you to acces the data in a SQL-like or relational way. - -### Drizzle Kit - -Drizzle Kit is a tool used to generate and run SQL migration files. -It also comes with Drizzle Studio, a database visualising and interaction tool. - -### Drizzle Seed - -Drizzle Seed is a TypeScript library that helps you generate deterministic, yet realistic, fake data to populate your database. -By leveraging a seedable pseudorandom number generator (pRNG), it ensures that the data you generate is consistent and reproducible across different runs. - -## Why Drizzle? - -We use drizzle because it gives us easy definitions of tables in our database, but doesn't abstract too much away from the actual database. -There is also a lot of good tools to make Drizzle fit with our other tools. - -## How we use Drizzle - -Drizzle is used all all over the place: - -- table declaration ([db/tables](https://github.com/vektorprogrammet/api/tree/main/db/tables)) -- database migration ([db/config](https://github.com/vektorprogrammet/api/blob/main/db/config/drizzle.config.ts)) -- database access ([src/db-access](https://github.com/vektorprogrammet/api/blob/main/src/db-access)) - -## Drizzle learning resources - -Drizzle ORM in 100 seconds: - -Intro video to Drizzle: - -Drizzle Guides for common task: - -Official documentation: - -Officail sourcecode: - -NPM packages: - -- ORM: -- kit: -- seed: diff --git a/backend/learn-express.md b/backend/learn-express.md deleted file mode 100644 index 7ecca12..0000000 --- a/backend/learn-express.md +++ /dev/null @@ -1,70 +0,0 @@ -# Learn Express - -- [Learn Express](#learn-express) - - [What is Express?](#what-is-express) - - [What are RESTful APIs?](#what-are-restful-apis) - - [What are HTTP requests?](#what-are-http-requests) - - [Why Express?](#why-express) - - [How we use Express](#how-we-use-express) - - [Express learning resources](#express-learning-resources) - -## What is Express? - -Express is a back end web application framework for building RESTful APIs with Node.js. - -### What are RESTful APIs? - -REST(REpresentational State Transfer) is a architecture style describing how a multimedia system exposed to the internet should behave. - -A core principle in REST is that the client and server don't need to know what state the other is in. -This makes it easier to create reliable interfaces over the web. - -A RESTful api requires the client to send HTTP-requests to the server - -### What are HTTP requests? - -Http requests consists of: - -- a path to a resource -- an HTTP verb, which defines what kind of operation to perform -- a header, which allows the client to pass along information about the request -- an optional message body containing data - -There are four basic HTTP request verbs: GET, POST, PUT and delete. -These corresponds to the four CRUD operations - -Read more about the CRUD operations on Wikipedia: - -- -- - -## Why Express? - -We use Express because it is one of the most vidley used web application frameworks both in Node and in general. -It is easy to use and has a good amount of both official documentation and tutorials all availible online. - -## How we use Express - -We use Express to listen for requests to our server from the frontend. See: - -- [src/main](https://github.com/vektorprogrammet/api/blob/main/src/main.ts) -- [src/routes](https://github.com/vektorprogrammet/api/tree/main/src/routers) - -## Express learning resources - -RESTful APIs in 100 seconds: - -HTTP request methods: - -Wikipedia: - -- english: -- norwegian: - -Official documentation: - -Official sourcecode: - -Official wiki: - -NPM package: diff --git a/backend/learn-zod.md b/backend/learn-zod.md deleted file mode 100644 index d489909..0000000 --- a/backend/learn-zod.md +++ /dev/null @@ -1,48 +0,0 @@ -# Learn Zod - -## Table of contents - -- [Learn Zod](#learn-zod) - - [Table of contents](#table-of-contents) - - [What is Zod?](#what-is-zod) - - [Why Zod?](#why-zod) - - [How we use Zod](#how-we-use-zod) - - [Zod learning resources](#zod-learning-resources) - -## What is Zod? - -Zod is a schema declaration and validation library. -The term "schema" broadly refers to any data type, from a simple string to a complex nested object. - -## Why Zod? - -Typescript has a powerful and complex type system. -This fact might make you wonder why we would need Zod to validate our literals and objects. -Well, the fact is also that while Typescript has a powerful typesystem, it is built upon a language with no types. This often makes it hard to verify types at runtime, either because they originate from a pure-javascript module, or if your object is parsed from a string or similar. -Zod therefore introduces features for parsing objects and literals at runtime. -This is incredibly usefull, becuase writing such code on your own can get incredibly convoluted. - -To read more about the motivation for Zod and other Zod alternatives, see this blockpost by the creator: - -## How we use Zod - -We use Zod to parse: - -- API requests (see [src/requestparsing](https://github.com/vektorprogrammet/api/tree/main/src/response-handling)) - - url queries - - parameters - - json bodies -- database errors (see [db/errors](https://github.com/vektorprogrammet/api/tree/main/db/errors)) -- enviromentvariables (see [src/enviroment](https://github.com/vektorprogrammet/api/blob/main/src/enviroment.ts) or [db/config/parameters](https://github.com/vektorprogrammet/api/blob/main/db/config/parameters.ts)) - -## Zod learning resources - -Intro video to Zod: - -Some Zod exercises: - -Official documentation: - -Official source code: - -NPM package: diff --git a/learn-backend.md b/learn-backend.md new file mode 100644 index 0000000..c45e429 --- /dev/null +++ b/learn-backend.md @@ -0,0 +1,261 @@ +# Learn Backend + +- [Learn Backend](#learn-backend) + - [Node | Running JavaScript on the server](#node--running-javascript-on-the-server) + - [Express](#express) + - [Why Express?](#why-express) + - [How we use Express](#how-we-use-express) + - [Express learning resources](#express-learning-resources) + - [Drizzle](#drizzle) + - [Drizzle ORM](#drizzle-orm) + - [Drizzle Kit](#drizzle-kit) + - [Drizzle Seed](#drizzle-seed) + - [Why Drizzle?](#why-drizzle) + - [How we use Drizzle](#how-we-use-drizzle) + - [Drizzle learning resources](#drizzle-learning-resources) + - [Zod](#zod) + - [Why Zod?](#why-zod) + - [How we use Zod](#how-we-use-zod) + - [Zod learning resources](#zod-learning-resources) + - [Testing](#testing) + - [Node test runner](#node-test-runner) + - [Node assert](#node-assert) + - [Supertest](#supertest) + - [Insomnia](#insomnia) + - [API Documentation](#api-documentation) + - [Swagger](#swagger) + - [ZodOpenAPI](#zodopenapi) + - [How to add OpenAPI specifications](#how-to-add-openapi-specifications) + - [How to add a resource to the specification](#how-to-add-a-resource-to-the-specification) + - [How to add a scema to the specification](#how-to-add-a-scema-to-the-specification) + - [Appendix](#appendix) + - [REST API](#rest-api) + - [HTTP Requests](#http-requests) + +## Node | Running JavaScript on the server + + + +## Express + +Express is a back end web application framework for building [REST APIs](#rest-api) with Node. + +### Why Express? + +We use Express because it is one of the most vidley used web application frameworks both in Node and in general. +It is easy to use and has a good amount of both official documentation and tutorials all availible online. + +### How we use Express + +We use Express to listen for requests to our server from the frontend. See: + +- [src/main](https://github.com/vektorprogrammet/api/blob/main/src/main.ts) +- [src/routes](https://github.com/vektorprogrammet/api/tree/main/src/routers) + +### Express learning resources + +Wikipedia: + +- english: +- norwegian: + +Official documentation: + +Official sourcecode: + +Official wiki: + +NPM package: + +## Drizzle + +Drizzle ORM is a collection of database management and access tools. +The most promintent one is Drizzle ORM. +But there is also Drizzle Kit and Drizzle Seed. + +### Drizzle ORM + +Drizzle ORM is a object relational mapper (ORM) and is used to define and manage database schemas, and also allows you to acces the data in a SQL-like or relational way. + +### Drizzle Kit + +Drizzle Kit is a tool used to generate and run SQL migration files. +It also comes with Drizzle Studio, a database visualising and interaction tool. + +### Drizzle Seed + +Drizzle Seed is a TypeScript library that helps you generate deterministic, yet realistic, fake data to populate your database. +By leveraging a seedable pseudorandom number generator (pRNG), it ensures that the data you generate is consistent and reproducible across different runs. + +### Why Drizzle? + +We use drizzle because it gives us easy definitions of tables in our database, but doesn't abstract too much away from the actual database. +There is also a lot of good tools to make Drizzle fit with our other tools. + +### How we use Drizzle + +Drizzle is used all all over the place: + +- table declaration ([db/tables](https://github.com/vektorprogrammet/api/tree/main/db/tables)) +- database migration ([db/config](https://github.com/vektorprogrammet/api/blob/main/db/config/drizzle.config.ts)) +- database access ([src/db-access](https://github.com/vektorprogrammet/api/blob/main/src/db-access)) + +### Drizzle learning resources + +Drizzle ORM in 100 seconds: + +Intro video to Drizzle: + +Drizzle Guides for common task: + +Official documentation: + +Officail sourcecode: + +NPM packages: + +- ORM: +- kit: +- seed: + +## Zod + +Zod is a schema declaration and validation library. +The term "schema" broadly refers to any data type, from a simple string to a complex nested object. + +### Why Zod? + +Typescript has a powerful and complex type system. +This fact might make you wonder why we would need Zod to validate our literals and objects. +Well, the fact is also that while Typescript has a powerful typesystem, it is built upon a language with no types. This often makes it hard to verify types at runtime, either because they originate from a pure-javascript module, or if your object is parsed from a string or similar. +Zod therefore introduces features for parsing objects and literals at runtime. +This is incredibly useful, becuase writing such code on your own can get incredibly convoluted. + +To read more about the motivation for Zod and other Zod alternatives, see this blockpost by the creator: + +### How we use Zod + +We use Zod to parse: + +- API requests (see [src/requestparsing](https://github.com/vektorprogrammet/api/tree/main/src/response-handling)) + - url queries + - parameters + - json bodies +- database errors (see [db/errors](https://github.com/vektorprogrammet/api/tree/main/db/errors)) +- enviromentvariables (see [src/enviroment](https://github.com/vektorprogrammet/api/blob/main/src/enviroment.ts) or [db/config/parameters](https://github.com/vektorprogrammet/api/blob/main/db/config/parameters.ts)) + +### Zod learning resources + +Intro video to Zod: + +Some Zod exercises: + +Official documentation: + +Official source code: + +NPM package: + +## Testing + +### [Node test runner](https://nodejs.org/docs/latest-v22.x/api/test.html) + +Node testrunner is a built in Node module we use to run tests with. +It is important that you verify thar you use Node version 22 or higher, in order to make this module work as expected. + +### [Node assert](https://nodejs.org/docs/latest-v22.x/api/assert.html) + +Node assert is a built in Node library containing a set of functions for verifying correctedness in tests. + +### [Supertest](https://www.npmjs.com/package/supertest) + +Supertest is a HTTP testing tool, built on Superagent. +We use it to run different HTTP requests to our API in order to check that it returns the correct responses. + +### [Insomnia](https://insomnia.rest/) + +Insomnia is an open source desktop application used for interacting with and designing, debugging, and testing APIs. We use it to usertest that specific requests works as expected. + +Official documentation: +Download page: + +## API Documentation + +### [Swagger](https://swagger.io/docs/specification/v3_0/about/) + +Swagger is a set tools that easier to follow the OpenAPI specification. +We use the swagger-ui-express tool to host our openapi specification in our api itself. +We use the swagger-jsdoc NPM package to write openapi specifications in jsdoc comments directly in the code, to make the specifications easier to write and read, when you can look at the code in the same place. + +### [ZodOpenAPI](https://www.npmjs.com/package/zod-openapi) + +A tool used to transform our Zod scemas to schemas we can use in our OpenAPI specification. + +### How to add OpenAPI specifications + +#### How to add a resource to the specification + +To add an addition to the OpenAPI specification, you need to add a comment following this format: + +```yaml +/** + * @openapi + * /path/to/your/resource: + * (http verb here): + * tags: [some, tags, in, here] + * summary: "Here goes the summary" + * description: "And here the description" + * parameters: + * - $ref: "#/components/parameters/yourParameterHere" + * requestBody: + * required: true + * content: + * json: + * schema: + * $ref: "#/components/schemas/yourRequestScema" + * responses: + * (response code here): + * description: "Description of your response + * content: + * application/json: + * schema: + * $ref: "#/components/schemas/yourReturnScema" + */ +``` + +#### How to add a scema to the specification + +In order to add a Zod schema to the OpenAPI specification, go to [the openapi configuration file](https://github.com/vektorprogrammet/api/blob/main/src/openapi/config.ts). +Under components you can add your schema. Remember that when you reference you scema in the specification, use the key assigned it with here. + +## Appendix + +### REST API + +RESTful APIs in 100 seconds: + +REST(REpresentational State Transfer) is a architecture style describing how a multimedia system exposed to the internet should behave. + +A core principle in REST is that the client and server don't need to know what state the other is in. +This makes it easier to create reliable interfaces over the web. + +A RESTful api requires the client to send HTTP-requests to the server + +### HTTP Requests + +HTTP request methods: + +Http requests consists of: + +- a path to a resource +- an HTTP verb, which defines what kind of operation to perform +- a header, which allows the client to pass along information about the request +- an optional message body containing data + +There are four basic HTTP request verbs: GET, POST, PUT and delete. +These corresponds to the four CRUD operations + +Read more about the CRUD operations on Wikipedia: + +- +-