Skip to content

Commit

Permalink
feat(docs): improve examples
Browse files Browse the repository at this point in the history
  • Loading branch information
jlenon7 committed Aug 14, 2023
1 parent 12862b9 commit ee43b41
Show file tree
Hide file tree
Showing 20 changed files with 121 additions and 82 deletions.
33 changes: 17 additions & 16 deletions docs/architecture-concepts/application-lifecycle.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ application you are using. Meaning that no matter what is the type of
application you are using to build your solution, the explanation bellow
is valid for all of them.

The entry point of an Athenna application is the `Path.bootstrap('main.js')`.
The entry point of an Athenna application is the `Path.bootstrap('main.ts')`.
The first action taken by Athenna itself is to create an instance of the
application and then boot it.

Expand Down Expand Up @@ -118,10 +118,11 @@ in the `.athennarc.json` in the `preloads` array.
:::note

The process of firing the Athenna foundation is triggered by the
`Ignite.fire` method. But if you check your `main.ts` entrypoint file,
you will see that this method is not called directly. The reason for
this is that this method is called internally depending on the type of
application you are using. Let's cover some examples bellow:
`Ignite::fire()` static method. But if you check your `Path.bootstrap('main.ts')`
entrypoint file, you will see that this method is not called directly.
The reason for this is that this method is called internally depending
on the type of application you are using. Let's cover some examples
bellow:

- The `REST API` application needs to fire the foundation first because
it depends on service providers to register your controllers, services,
Expand All @@ -140,7 +141,7 @@ will be fired before executing your command.
### Kernel

The Kernel class is responsible by defining some bootstraps that will
be run before reading your `Path.routes('http.js')` file. These bootstraps
be run before reading your `Path.routes('http.ts')` file. These bootstraps
configure error handling for requests, tracing and logging, detect the
application environment, and perform other tasks that need to be done
before the request is actually handled. Typically, these classes handle
Expand Down Expand Up @@ -168,7 +169,7 @@ implementation code.

:::

Then, you can register your `CustomKernel` in your `Path.bootstrap('main.js')`
Then, you can register your `CustomKernel` in your `Path.bootstrap('main.ts')`
file:

```typescript
Expand All @@ -181,14 +182,14 @@ await ignite.httpServer({ kernelPath: '#app/http/CustomKernel' })

### Routes

The `Path.routes('http.js')` file is the entrypoint for all your http requests.
The `Path.routes('http.ts')` file is the entrypoint for all your http requests.
This file is responsible to create a contract between your client and
your application. It Is in here that we define all our routes and the
handlers/controllers who will handle the client request.

One of the most important service providers in your application is the
`HttpRouteProvider`. This service provider adds in the container the
`Route` class instance used inside `Path.routes('http.js')` file.
`Route` class instance used inside `Path.routes('http.ts')` file.

When the client request arrives, the server first executes all your
global middlewares, then it will execute all your route middlewares.
Expand Down Expand Up @@ -275,8 +276,8 @@ kernel implementation taking a look at [ConsoleKernel](https://github.com/Athenn

:::

Then, you can register your `CustomKernel` in your `Path.bootstrap('main.js')` or
`Path.bootstrap('artisan.js')` file:
Then, you can register your `CustomKernel` in your
`Path.bootstrap('main.ts')` or `Path.bootstrap('artisan.ts')` file:

```typescript
import { Ignite } from '@athenna/core'
Expand All @@ -290,9 +291,9 @@ await ignite.artisan({ kernelPath: '#app/http/CustomKernel' })

### Execution

The `Path.routes('console.js')` and the `commands` property of `.athennarc.json` file
is where that we define all ours commands and the handlers who will handle
the terminal arguments.
The `Path.routes('console.ts')` and the `commands` property of
`.athennarc.json` file is where that we define all ours commands
and the handlers who will handle the terminal arguments.

When the terminal arguments arrive, the application will be bootstrapped
based on the command that you are asking to execute. Let's suppose we have
Expand All @@ -318,10 +319,10 @@ command and execute it:
```mermaid
flowchart LR
terminalCommand(("Terminal Command"))
igniteLoad{"Ignite.load()"}
igniteLoad{"Ignite::load()"}
consoleKernel{"ConsoleKernel"}
loadAppEqualsTrue{"loadApp === true"}
igniteFire{"Ignite.fire()"}
igniteFire{"Ignite::fire()"}
defineArgsAndFlags{"Define arguments and flags"}
commandHandler("Command Handler")
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture-concepts/service-container.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ itself.
If you use the `@Service` annotation, you can instruct the container how he
should resolve that class, or use the default resolution configurations of the
annotation. For example, you may place the following code in your
`Path.routes('http.js')` file:
`Path.routes('http.ts')` file:

```typescript
import { Route } from '@athenna/http'
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture-concepts/service-providers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ The following environments are available by default in Athenna at this moment:
- repl
- console

You could also create your own environments. In your `Path.bootstrap('main.js')` file
You could also create your own environments. In your `Path.bootstrap('main.ts')` file
you can add an `environments` option when calling `Ignite.load` method:

```typescript
Expand Down
14 changes: 7 additions & 7 deletions docs/cli-application/error-handling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ This documentation will cover about error handling in the **CLI**
application, which means that only errors that happens inside
the `handle()` method of commands and bellow that will be handled:

```typescript title="app/console/commands/AppCommand.ts"
```typescript title="app/console/commands/AppCommand.js"
import { BaseCommand } from '@athenna/artisan'
import { AppService } from '#app/services/AppService'

Expand Down Expand Up @@ -62,7 +62,7 @@ bootstrap failure has been found in your application.

## Configuration

The `debug` option in your `Path.config('app.js')` configuration
The `debug` option in your `Path.config('app.ts')` configuration
file determines how much information about an error is
actually displayed to the user. By default, this option is
set to respect the value of the `APP_DEBUG` environment
Expand All @@ -77,13 +77,13 @@ users.

Every error will be logged by default using the `console`
driver from `@athenna/logger`. By default, Athenna uses the
`exception` channel of your `Path.config('logging.js')` file to log
`exception` channel of your `Path.config('logging.ts')` file to log
all exceptions that happens in your application.

:::tip

You can change the driver and formatter of `exception`
channel inside `Path.config('logging.js')` file. This way you can
channel inside `Path.config('logging.ts')` file. This way you can
send all your error logs to another provider and with
a different formatter.

Expand Down Expand Up @@ -128,7 +128,7 @@ Simple exceptions are recognized by `ConsoleExceptionHandler` by
the `code`. If the code is `E_SIMPLE_CLI`, it will be considered
as a simple exception:

```typescript title="app/console/exceptions/NotFoundDatabaseException.ts"
```typescript title="app/console/exceptions/NotFoundDatabaseException.js"
import { Exception } from '@athenna/common'

export class NotFoundDatabaseException extends Exception {
Expand All @@ -146,7 +146,7 @@ Let's suppose you want to write a custom logic for handling
your exceptions. You can do so by creating your own
exception handler:

```typescript title="app/console/exceptions/Handler.ts"
```typescript title="app/console/exceptions/Handler.js"
import { ConsoleExceptionHandler } from '@athenna/artisan'

export class Handler extends ConsoleExceptionHandler {
Expand All @@ -159,7 +159,7 @@ export class Handler extends ConsoleExceptionHandler {
Now you need to register your exception handler when
bootstrapping your application:

```typescript filename="Path.bootstrap('main.js')"
```typescript title="Path.bootstrap('main.ts')"
await ignite.artisan(process.argv, {
displayName: 'Athenna',
exceptionHandlerPath: '#app/console/exceptions/Handler', 👈
Expand Down
38 changes: 38 additions & 0 deletions docs/cli-application/running.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,41 @@ And now the `yourCliCommand` will exist in your actual Node.js version:
```shell
yourCliCommand --help
```

## Display CLI name

When running your CLI without any option and command, the display
name will be rendered in the terminal using
[`chalk-rainbow`](https://www.npmjs.com/package/chalk-rainbow)
and [`figlet`](https://www.npmjs.com/package/figlet).

By default Artisan always display the `Artisan` name, but you can
change it for your own display name by setting the `displayName`
property in `Ignite.artisan()` method:

```typescript title="Path.bootstrap('main.ts')"
import { Ignite } from '@athenna/core'

const ignite = await new Ignite().load(import.meta.url)

await ignite.artisan({
displayName: 'Your CLI Command', 👈
})
```

:::tip

If you wish to disable the display name, just set the `displayName`
as `null`:

```typescript title="Path.bootstrap('main.ts')"
import { Ignite } from '@athenna/core'

const ignite = await new Ignite().load(import.meta.url)

await ignite.artisan({
displayName: null, 👈
})
```

:::
4 changes: 2 additions & 2 deletions docs/digging-deeper/graceful-shutdown.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ listeners you want, this means that you can use the default
your own. We recommend doing this implementation in the bootstrap
file of your like application:

```typescript filename="Path.bootstrap('main.js')"
```typescript title="Path.bootstrap('main.ts')"
import { Ignite } from '@athenna/core'

const ignite = await new Ignite().load(import.meta.url)
Expand All @@ -125,7 +125,7 @@ process.on('SIGTERM', () => {

If you wish to remove or change the default listeners of
Athenna, or also listen to new signals, you can create
the `signals` property in the `Path.config('app.js')`
the `signals` property in the `Path.config('app.ts')`
file:

```typescript
Expand Down
4 changes: 2 additions & 2 deletions docs/digging-deeper/repl.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ run the Artisan command:
:::info

When running this command, Athenna will use the
`Path.bootstrap('repl.js')` file to execute your session.
`Path.bootstrap('repl.ts')` file to execute your session.

:::

Expand Down Expand Up @@ -72,7 +72,7 @@ commands available.

You can pre-import modules in your REPL session to avoid keep
importing them everytime inside your REPL session. You can do that
in your `Path.bootstrap('repl.js')` file:
in your `Path.bootstrap('repl.ts')` file:

```typescript
import { Ignite } from '@athenna/core'
Expand Down
8 changes: 4 additions & 4 deletions docs/getting-started/athennarc-file.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ also register it inside your `.athennarc.json` file:
You can change the name and the path of your RC file or even
create customized ones for each environement (`.athennarc.dev.json`,
`.athennarc.prod.json`). To do that you need to set the new
path to `Ignite.load()` method:
path to `Ignite::load()` static method:

```typescript filename="Path.bootstrap('dev.js')"
```typescript title="Path.bootstrap('dev.ts')"
import { Ignite } from '@athenna/core'

const ignite = await new Ignite().load(import.meta.url, {
Expand All @@ -74,7 +74,7 @@ If you don't specify the path of your RC file, and the default
`.athennarc.json` cannot be found in the root path of your application,
Athenna will check if the `athenna` property exists in your `package.json`:

```json filename="package.json"
```json title="package.json"
{
"athenna": {
"providers": [
Expand All @@ -96,7 +96,7 @@ is bootstrapping. The files are loaded after booting the
service providers. You can do anything you want in preload
files. Check the example bellow:

```typescript filename="say-hello.js"
```typescript title="say-hello.js"
import { Log } from '@athenna/logger'
import { Config } from '@athenna/core'

Expand Down
14 changes: 7 additions & 7 deletions docs/getting-started/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -192,9 +192,9 @@ console.log(Env('APP_URL')) // "http://localhost:3000"
## Custom environment file path

You can also change the name and the path of your `.env` file.
To do that you need to set the new path to `Ignite.load()` method:
To do that you need to set the new path to `Ignite::load()` static method:

```typescript filename="Path.bootstrap('dev.js')"
```typescript title="Path.bootstrap('dev.ts')"
import { Ignite } from '@athenna/core'

const ignite = await new Ignite().load(import.meta.url, {
Expand Down Expand Up @@ -361,7 +361,7 @@ Config.set('app.name', builders.functionCall('Env', ['MY_APP_NAME']))
await Config.rewrite('app')
```

The example above will produce the following code in `Path.config('app.js')`:
The example above will produce the following code in `Path.config('app.ts')`:

```typescript
export default {
Expand Down Expand Up @@ -445,7 +445,7 @@ file path:
import { Path } from '@athenna/common'
import { Config } from '@athenna/config'

await Config.load(Path.stubs('config/test.js'))
await Config.load(Path.stubs('config/test.ts'))

console.log(Config.get('test')) // { ... }
```
Expand Down Expand Up @@ -557,9 +557,9 @@ and them by the HTTP server.
This is usually not a problem at all, but depending on how you have created
your environment it could become one. To avoid reloading configuration
files in these situations, you can set the `loadConfigSafe` option as `true`
in `Ignite.load()` method:
in `Ignite::load()` static method:

```typescript filename="Path.bootstrap('main.js')"
```typescript title="Path.bootstrap('main.ts')"
import { Ignite } from '@athenna/core'

const ignite = await new Ignite().load(import.meta.url, {
Expand All @@ -571,7 +571,7 @@ await ignite.httpServer()

## Debug mode

The `debug` option in your `Path.config('app.js')` configuration
The `debug` option in your `Path.config('app.ts')` configuration
file determines how much information about your application
is actually displayed to you and for who is going to consume
your application. By default, this option is set to respect
Expand Down
16 changes: 8 additions & 8 deletions docs/getting-started/directory-structure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ the classes in your application will be in this directory.
### The bootstrap directory

The `bootstrap` directory contains all of your application's
bootstrap files. It's here that Athenna holds the `main.ts`
bootstrap files. It's here that Athenna holds the `main.js`
file that bootstrap the application using the `Ignite` class.

### The config directory
Expand Down Expand Up @@ -71,17 +71,17 @@ The `routes` directory contains all the route definitions
for your application. By default, several route files are
included with Athenna:

- The `http.ts` file is where you will define the entry
- The `http.js` file is where you will define the entry
point of your api using the Route facade that is provided
by the HttpRouteProvider.
- The `console.ts` file is where you will define the entry
- The `console.js` file is where you will define the entry
point of your commands using the Artisan facade that is
provided by the ArtisanProvider.

:::important

As you may have noticed your project does not have the
`console.ts` file. We only recommend using this file when
`console.js` file. We only recommend using this file when
you don't want to use TypeScript in your application or
when you want to add some personalized option of [commander](https://www.npmjs.com/package/commander)
to your command. Check the example:
Expand Down Expand Up @@ -126,7 +126,7 @@ command.
If your test file name does not end with `Test`, it will
be ignored and the test class will not run. But, you can
customize this behavior in the configure function of [Japa](https://japa.dev/docs)
inside your `Path.bootstrap('test.js')` file.
inside your `Path.bootstrap('test.ts')` file.

:::

Expand All @@ -144,16 +144,16 @@ create the project:
There are some files in your project that are crucial to
keep in certain places. Let's analyze some of them:

- The `Path.bootstrap('main.js')` file is the entry point of the
- The `Path.bootstrap('main.ts')` file is the entry point of the
`./node artisan serve` command. Every time that you run this
command, Athenna will use this file to run your application.
- The `Path.bootstrap('artisan.js')` file is the entry point of the
- The `Path.bootstrap('artisan.ts')` file is the entry point of the
`./node artisan` script. You can check how this works in the
[node script file documentation section](https://athenna.io/docs/getting-started/node-script-file).
- The `config` path is where you are going to set up your
configuration files. You can learn more about configuration
files at [the configuration documentation section](https://athenna.io/docs/getting-started/configuration).
- The `Path.routes('http.js')` file is where you are going to register
- The `Path.routes('http.ts')` file is where you are going to register
your Http server routes.

Athenna is a framework with a lot of opinions, with predefined
Expand Down
Loading

0 comments on commit ee43b41

Please sign in to comment.