[//]: # ( )
[//]: # (This file is automatically generated by a `metapak`)
[//]: # (module. Do not change it  except between the)
[//]: # (`content:start/end` flags, your changes would)
[//]: # (be overridden.)
[//]: # ( )
# @whook/example
> A basic Whook server

[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nfroidure/whook/blob/main/packages/whook-example/LICENSE)


[//]: # (::contents:start)

This is a basic [Whook](https://github.com/nfroidure/whook) server demonstrating
the various usages of the Whook framework to build REST APIs.

## Usage

To run the server in production:

```sh
# For the first time create a strong JWT secret
echo 'JWT_SECRET=$(openssl rand -base64 10)' > .env.app.production
# And install the dependencies
npm i

# Then and later, just run build and run the server
npm run build

NODE_ENV=production APP_ENV=production node --run start
```

You can understand deeply this repository and Whook's internal by simply reading
the [Architecture Notes](./ARCHITECTURE.md). The "See in context" links drive
your directly in the concerned implementation so that you can just see the code
that explains the notes.

Feel free to continue creating architecture notes and to regenerate the markdown
file by running:

```sh
node --run architecture
```

## Dev

Start the server in development:

```sh
# Simple dev mode
node --run dev

# Watch mode
node --run watch
```

Run and update tests:
```sh
# Run the tests
npm t

# Updating tests snapshots
node --run jest -- -u
```

Create a new route / cron / service / provider or command:

```sh
node --run create
```

Play with the REPL:

```sh
node --run repl
```

Generate the dependency injection graph (here, for the `putTime` handler):

```sh
node --run whook -- __inject putTime,mermaid > DEPENDENCIES.mmd;
docker run --rm -u `id -u`:`id -g` -v $(pwd):/data minlag/mermaid-cli -i DEPENDENCIES.mmd -o DEPENDENCIES.mmd.svg;
```

List available commands:

```sh
## In dev mode
node --run dev -- ls
## With built files
npx whook ls
```

Generate API types:

```sh
node --run apitypes
```

## Debug

Execute a route handler in isolation:

```sh
node --run dev -- route --name putEcho --parameters '{"body": { "echo": "YOLO!" }}'
```

Execute a cron handler in isolation:

```sh
node --run dev -- cronRun --name handleMinutes --date '2025-03-15T17:00:00Z'
```

Debug `whook` internals:

```sh
DEBUG=whook node --run dev
```

Debug `knifecycle` internals (dependency injection issues):

```sh
DEBUG=knifecycle node --run dev
```

[//]: # (::contents:end)

# Authors
- [Nicolas Froidure](http://insertafter.com/en/index.html)

# License
[MIT](https://github.com/nfroidure/whook/blob/main/packages/whook-example/LICENSE)