node-fastify 5.8.3

package/docs/Guides/Style-Guide.md

@@ -0,0 +1,246 @@
+# Fastify Style Guide
+
+## Welcome
+
+Welcome to *Fastify Style Guide*. This guide is here to provide you with a
+conventional writing style for users writing developer documentation on our Open
+Source framework. Each topic is precise and well explained to help you write
+documentation users can easily understand and implement.
+
+## Who is this guide for?
+
+This guide is for anyone who loves to build with Fastify or wants to contribute
+to our documentation. You do not need to be an expert in writing technical
+documentation. This guide is here to help you.
+
+Visit the [contribute](https://fastify.dev/contribute) page on our website or
+read the
+[CONTRIBUTING.md](https://github.com/fastify/fastify/blob/main/CONTRIBUTING.md)
+file on GitHub to join our Open Source folks.
+
+## Before you write
+
+You need to know the following:
+
+* JavaScript
+* Node.js
+* Git
+* GitHub
+* Markdown
+* HTTP
+* NPM
+
+### Consider your Audience
+
+Before you start writing, think about your audience. In this case, your audience
+should already know HTTP, JavaScript, NPM, and Node.js. It is necessary to keep
+your readers in mind because they are the ones consuming your content. You want
+to give as much useful information as possible. Consider the vital things they
+need to know and how they can understand them. Use words and references that
+readers can relate to easily. Ask for feedback from the community, it can help
+you write better documentation that focuses on the user and what you want to
+achieve.
+
+### Get straight to the point
+
+Give your readers a clear and precise action to take. Start with what is most
+important. This way, you can help them find what they need faster. Mostly,
+readers tend to read the first content on a page, and many will not scroll
+further.
+
+**Example**
+
+Less like this: Colons are very important to register a parametric path. It lets
+the framework know there is a new parameter created. You can place the colon
+before the parameter name so the parametric path can be created.
+
+More Like this: To register a parametric path, put a colon before the parameter
+name. Using a colon lets the framework know it is a parametric path and not a
+static path.
+
+### Avoid adding video or image content
+
+
+Do not add videos or screenshots to the documentation. It is easier to keep
+under version control. Videos and images will eventually end up becoming
+outdated as new updates keep developing. Instead, make a referral link or a
+YouTube video. You can add links by using `[Title](www.websitename.com)` in the
+markdown.
+
+**Example**
+
+```
+To learn more about hooks, see [Fastify hooks](https://fastify.dev/docs/latest/Reference/Hooks/).
+```
+
+Result:
+>To learn more about hooks, see [Fastify
+>hooks](https://fastify.dev/docs/latest/Reference/Hooks/).
+
+
+
+### Avoid plagiarism
+
+Make sure you avoid copying other people's work. Keep it as original as
+possible. You can learn from what they have done and reference where it is from
+if you use a particular quote from their work.
+
+
+## Word Choice
+
+There are a few things you need to use and avoid when writing your documentation
+to improve readability for readers and make documentation neat, direct, and
+clean.
+
+
+### When to use the second person "you" as the pronoun
+
+When writing articles or guides, your content should communicate directly to
+readers in the second person ("you") addressed form. It is easier to give them
+direct instruction on what to do on a particular topic. To see an example, visit
+the [Plugins Guide](./Plugins-Guide.md).
+
+**Example**
+
+Less like this: we can use the following plugins.
+
+More like this: You can use the following plugins.
+
+> According to [Wikipedia](#), ***You*** is usually a second person pronoun.
+> Also, used to refer to an indeterminate person, as a more common alternative
+> to a very formal indefinite pronoun.
+
+## When to avoid the second person "you" as the pronoun
+
+One of the main rules of formal writing such as reference documentation, or API
+documentation, is to avoid the second person ("you") or directly addressing the
+reader.
+
+**Example**
+
+Less like this: You can use the following recommendation as an example.
+
+More like this: As an example, the following recommendations should be
+referenced.
+
+To view a live example, refer to the [Decorators](../Reference/Decorators.md)
+reference document.
+
+
+### Avoid using contractions
+
+Contractions are the shortened version of written and spoken forms of a word,
+i.e. using "don't" instead of "do not". Avoid contractions to provide a more
+formal tone.
+
+### Avoid using condescending terms
+
+Condescending terms are words that include:
+
+* Just
+* Easy
+* Simply
+* Basically
+* Obviously
+
+The reader may not find it easy to use Fastify's framework and plugins; avoid
+words that make it sound simple, easy, offensive, or insensitive. Not everyone
+who reads the documentation has the same level of understanding.
+
+
+### Starting with a verb
+
+Mostly start your description with a verb, which makes it simple and precise for
+the reader to follow. Prefer using present tense because it is easier to read
+and understand than the past or future tense.
+
+**Example**
+
+ Less like this: There is a need for Node.js to be installed before you can be
+ able to use Fastify.
+
+ More like this: Install Node.js to make use of Fastify.
+
+### Grammatical moods
+
+Grammatical moods are a great way to express your writing. Avoid sounding too
+bossy while making a direct statement. Know when to switch between indicative,
+imperative, and subjunctive moods.
+
+
+**Indicative** - Use when making a factual statement or question.
+
+Example: Since there is no testing framework available, "Fastify recommends ways
+to write tests".
+
+**Imperative** - Use when giving instructions, actions, commands, or when you
+write your headings.
+
+Example: Install dependencies before starting development.
+
+
+**Subjunctive** -  Use when making suggestions, hypotheses, or non-factual
+statements.
+
+Example: Reading the documentation on our website is recommended to get
+comprehensive knowledge of the framework.
+
+### Use **active** voice instead of **passive**
+
+Using active voice is a more compact and direct way of conveying your
+documentation.
+
+**Example**
+
+
+Passive: The node dependencies and packages are installed by npm.
+
+Active:  npm installs packages and node dependencies.
+
+## Writing Style
+
+### Documentation titles
+
+When creating a new guide, API, or reference in the `/docs/` directory, use
+short titles that best describe the topic of your documentation. Name your files
+in kebab-cases and avoid Raw or camelCase. To learn more about kebab-case you
+can visit this medium article on [Case
+Styles](https://medium.com/better-programming/string-case-styles-camel-pascal-snake-and-kebab-case-981407998841).
+
+**Examples**:
+
+>`hook-and-plugins.md`,
+
+ `adding-test-plugins.md`,
+
+ `removing-requests.md`.
+
+### Hyperlinks
+
+Hyperlinks should have a clear title of what they reference. Here is how your
+hyperlink should look:
+
+```MD
+<!-- More like this -->
+
+// Add clear & brief description
+[Fastify Plugins] (https://fastify.dev/docs/latest/Plugins/)
+
+<!--Less like this -->
+
+// incomplete description
+[Fastify] (https://fastify.dev/docs/latest/Plugins/)
+
+// Adding title in link brackets
+[](https://fastify.dev/docs/latest/Plugins/ "fastify plugin")
+
+// Empty title
+[](https://fastify.dev/docs/latest/Plugins/)
+
+// Adding links localhost URLs instead of using code strings (``)
+[http://localhost:3000/](http://localhost:3000/)
+
+```
+
+Include in your documentation as many essential references as possible, but
+avoid having numerous links when writing for beginners to avoid distractions.

package/docs/Guides/Testing.md

@@ -0,0 +1,481 @@
+<h1 style="text-align: center;">Fastify</h1>
+
+# Testing
+<a id="testing"></a>
+
+Testing is one of the most important parts of developing an application. Fastify
+is very flexible when it comes to testing and is compatible with most testing
+frameworks (such as [Node Test Runner](https://nodejs.org/api/test.html),
+which is used in the examples below).
+
+## Application
+
+Let's `cd` into a fresh directory called 'testing-example' and type `npm init
+-y` in our terminal.
+
+Run `npm i fastify && npm i pino-pretty -D`
+
+### Separating concerns makes testing easy
+
+First, we are going to separate our application code from our server code:
+
+**app.js**:
+
+```js
+'use strict'
+
+const fastify = require('fastify')
+
+function build(opts={}) {
+  const app = fastify(opts)
+  app.get('/', async function (request, reply) {
+    return { hello: 'world' }
+  })
+
+  return app
+}
+
+module.exports = build
+```
+
+**server.js**:
+
+```js
+'use strict'
+
+const server = require('./app')({
+  logger: {
+    level: 'info',
+    transport: {
+      target: 'pino-pretty'
+    }
+  }
+})
+
+server.listen({ port: 3000 }, (err, address) => {
+  if (err) {
+    server.log.error(err)
+    process.exit(1)
+  }
+})
+```
+
+### Benefits of using fastify.inject()
+
+Fastify comes with built-in support for fake HTTP injection thanks to
+[`light-my-request`](https://github.com/fastify/light-my-request).
+
+Before introducing any tests, we will use the `.inject` method to make a fake
+request to our route:
+
+**app.test.js**:
+
+```js
+'use strict'
+
+const build = require('./app')
+
+const test = async () => {
+  const app = build()
+
+  const response = await app.inject({
+    method: 'GET',
+    url: '/'
+  })
+
+  console.log('status code: ', response.statusCode)
+  console.log('body: ', response.body)
+}
+test()
+```
+
+First, our code will run inside an asynchronous function, giving us access to
+async/await.
+
+`.inject` ensures all registered plugins have booted up and our application is
+ready to test. Finally, we pass the request method we want to use and a route.
+Using await we can store the response without a callback.
+
+
+
+Run the test file in your terminal `node app.test.js`
+
+```sh
+status code:  200
+body:  {"hello":"world"}
+```
+
+
+
+### Testing with HTTP injection
+
+Now we can replace our `console.log` calls with actual tests!
+
+In your `package.json` change the "test" script to:
+
+`"test": "node --test --watch"`
+
+**app.test.js**:
+
+```js
+'use strict'
+
+const { test } = require('node:test')
+const build = require('./app')
+
+test('requests the "/" route', async t => {
+  t.plan(1)
+  const app = build()
+
+  const response = await app.inject({
+    method: 'GET',
+    url: '/'
+  })
+  t.assert.strictEqual(response.statusCode, 200, 'returns a status code of 200')
+})
+```
+
+Finally, run `npm test` in the terminal and see your test results!
+
+The `inject` method can do much more than a simple GET request to a URL:
+```js
+fastify.inject({
+  method: String,
+  url: String,
+  query: Object,
+  payload: Object,
+  headers: Object,
+  cookies: Object
+}, (error, response) => {
+  // your tests
+})
+```
+
+`.inject` methods can also be chained by omitting the callback function:
+
+```js
+fastify
+  .inject()
+  .get('/')
+  .headers({ foo: 'bar' })
+  .query({ foo: 'bar' })
+  .end((err, res) => { // the .end call will trigger the request
+    console.log(res.payload)
+  })
+```
+
+or in the promisified version
+
+```js
+fastify
+  .inject({
+    method: String,
+    url: String,
+    query: Object,
+    payload: Object,
+    headers: Object,
+    cookies: Object
+  })
+  .then(response => {
+    // your tests
+  })
+  .catch(err => {
+    // handle error
+  })
+```
+
+Async await is supported as well!
+```js
+try {
+  const res = await fastify.inject({ method: String, url: String, payload: Object, headers: Object })
+  // your tests
+} catch (err) {
+  // handle error
+}
+```
+
+#### Another Example:
+
+**app.js**
+```js
+const Fastify = require('fastify')
+
+function buildFastify () {
+  const fastify = Fastify()
+
+  fastify.get('/', function (request, reply) {
+    reply.send({ hello: 'world' })
+  })
+
+  return fastify
+}
+
+module.exports = buildFastify
+```
+
+**test.js**
+```js
+const { test } = require('node:test')
+const buildFastify = require('./app')
+
+test('GET `/` route', t => {
+  t.plan(4)
+
+  const fastify = buildFastify()
+
+  // At the end of your tests it is highly recommended to call `.close()`
+  // to ensure that all connections to external services get closed.
+  t.after(() => fastify.close())
+
+  fastify.inject({
+    method: 'GET',
+    url: '/'
+  }, (err, response) => {
+    t.assert.ifError(err)
+    t.assert.strictEqual(response.statusCode, 200)
+    t.assert.strictEqual(response.headers['content-type'], 'application/json; charset=utf-8')
+    t.assert.deepStrictEqual(response.json(), { hello: 'world' })
+  })
+})
+```
+
+### Testing with a running server
+Fastify can also be tested after starting the server with `fastify.listen()` or
+after initializing routes and plugins with `fastify.ready()`.
+
+#### Example:
+
+Uses **app.js** from the previous example.
+
+**test-listen.js** (testing with [`undici`](https://www.npmjs.com/package/undici))
+```js
+const { test } = require('node:test')
+const { Client } = require('undici')
+const buildFastify = require('./app')
+
+test('should work with undici', async t => {
+  t.plan(2)
+
+  const fastify = buildFastify()
+
+  await fastify.listen()
+
+   const client = new Client(
+    'http://localhost:' + fastify.server.address().port, {
+      keepAliveTimeout: 10,
+      keepAliveMaxTimeout: 10
+    }
+  )
+
+  t.after(() => {
+    fastify.close()
+    client.close()
+  })
+
+  const response = await client.request({ method: 'GET', path: '/' })
+
+  t.assert.strictEqual(await response.body.text(), '{"hello":"world"}')
+  t.assert.strictEqual(response.statusCode, 200)
+})
+```
+
+Alternatively, starting with Node.js 18,
+[`fetch`](https://nodejs.org/docs/latest-v18.x/api/globals.html#fetch)
+may be used without requiring any extra dependencies:
+
+**test-listen.js**
+```js
+const { test } = require('node:test')
+const buildFastify = require('./app')
+
+test('should work with fetch', async t => {
+  t.plan(3)
+
+  const fastify = buildFastify()
+
+  t.after(() => fastify.close())
+
+  await fastify.listen()
+
+  const response = await fetch(
+    'http://localhost:' + fastify.server.address().port
+  )
+
+  t.assert.strictEqual(response.status, 200)
+  t.assert.strictEqual(
+    response.headers.get('content-type'),
+    'application/json; charset=utf-8'
+  )
+  const jsonResult = await response.json()
+  t.assert.strictEqual(jsonResult.hello, 'world')
+})
+```
+
+**test-ready.js** (testing with
+[`SuperTest`](https://www.npmjs.com/package/supertest))
+```js
+const { test } = require('node:test')
+const supertest = require('supertest')
+const buildFastify = require('./app')
+
+test('GET `/` route', async (t) => {
+  const fastify = buildFastify()
+
+  t.after(() => fastify.close())
+
+  await fastify.ready()
+
+  const response = await supertest(fastify.server)
+    .get('/')
+    .expect(200)
+    .expect('Content-Type', 'application/json; charset=utf-8')
+  t.assert.deepStrictEqual(response.body, { hello: 'world' })
+})
+```
+
+### How to inspect node tests
+1. Isolate your test by passing the `{only: true}` option
+```javascript
+test('should ...', {only: true}, t => ...)
+```
+2. Run `node --test`
+```bash
+> node --test --test-only --inspect-brk test/<test-file.test.js>
+```
+- `--test-only` specifies to run tests with the `only` option enabled
+- `--inspect-brk` will launch the node debugger
+3. In VS Code, create and launch a `Node.js: Attach` debug configuration. No
+   modification should be necessary.
+
+Now you should be able to step through your test file (and the rest of
+`Fastify`) in your code editor.
+
+
+
+## Plugins
+Let's `cd` into a fresh directory called 'testing-plugin-example' and type
+`npm init -y` in our terminal.
+
+Run `npm i fastify fastify-plugin`
+
+**plugin/myFirstPlugin.js**:
+
+```js
+const fP = require("fastify-plugin")
+
+async function myPlugin(fastify, options) {
+    fastify.decorateRequest("helloRequest", "Hello World")
+    fastify.decorate("helloInstance", "Hello Fastify Instance")
+}
+
+module.exports = fP(myPlugin)
+```
+
+A basic example of a Plugin. See [Plugin Guide](./Plugins-Guide.md)
+
+**test/myFirstPlugin.test.js**:
+
+```js
+const Fastify = require("fastify");
+const { test } = require("node:test");
+const myPlugin = require("../plugin/myFirstPlugin");
+
+test("Test the Plugin Route", async t => {
+    // Create a mock fastify application to test the plugin
+    const fastify = Fastify()
+
+    fastify.register(myPlugin)
+
+    // Add an endpoint of your choice
+    fastify.get("/", async (request, reply) => {
+        return ({ message: request.helloRequest })
+    })
+
+    // Use fastify.inject to fake a HTTP Request
+    const fastifyResponse = await fastify.inject({
+        method: "GET",
+        url: "/"
+    })
+
+  console.log('status code: ', fastifyResponse.statusCode)
+  console.log('body: ', fastifyResponse.body)
+})
+```
+Learn more about [```fastify.inject()```](#benefits-of-using-fastifyinject).
+Run the test file in your terminal `node test/myFirstPlugin.test.js`
+
+```sh
+status code:  200
+body:  {"message":"Hello World"}
+```
+
+Now we can replace our `console.log` calls with actual tests!
+
+In your `package.json` change the "test" script to:
+
+`"test": "node --test --watch"`
+
+Create the test for the endpoint.
+
+**test/myFirstPlugin.test.js**:
+
+```js
+const Fastify = require("fastify");
+const { test } = require("node:test");
+const myPlugin = require("../plugin/myFirstPlugin");
+
+test("Test the Plugin Route", async t => {
+    // Specifies the number of test
+    t.plan(2)
+
+    const fastify = Fastify()
+
+    fastify.register(myPlugin)
+
+    fastify.get("/", async (request, reply) => {
+        return ({ message: request.helloRequest })
+    })
+
+    const fastifyResponse = await fastify.inject({
+        method: "GET",
+        url: "/"
+    })
+
+    t.assert.strictEqual(fastifyResponse.statusCode, 200)
+    t.assert.deepStrictEqual(JSON.parse(fastifyResponse.body), { message: "Hello World" })
+})
+```
+
+Finally, run `npm test` in the terminal and see your test results!
+
+Test the ```.decorate()``` and ```.decorateRequest()```.
+
+**test/myFirstPlugin.test.js**:
+
+```js
+const Fastify = require("fastify");
+const { test }= require("node:test");
+const myPlugin = require("../plugin/myFirstPlugin");
+
+test("Test the Plugin Route", async t => {
+    t.plan(5)
+    const fastify = Fastify()
+
+    fastify.register(myPlugin)
+
+    fastify.get("/", async (request, reply) => {
+        // Testing the fastify decorators
+        t.assert.ifError(request.helloRequest)
+        t.assert.ok(request.helloRequest, "Hello World")
+        t.assert.ok(fastify.helloInstance, "Hello Fastify Instance")
+        return ({ message: request.helloRequest })
+    })
+
+    const fastifyResponse = await fastify.inject({
+        method: "GET",
+        url: "/"
+    })
+    t.assert.strictEqual(fastifyResponse.statusCode, 200)
+    t.assert.deepStrictEqual(JSON.parse(fastifyResponse.body), { message: "Hello World" })
+})
+```