Skip to content

Commit

Permalink
Update docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
LoicPoullain committed May 31, 2018
1 parent 95b8c39 commit 41cc18d
Show file tree
Hide file tree
Showing 6 changed files with 34 additions and 38 deletions.
15 changes: 9 additions & 6 deletions docs/README.md
Expand Up @@ -6,20 +6,23 @@
</a>
</p>

FoalTS is the framework you need to build the backend of small to large web applications. As a brief overview, FoalTS lets you quickly set up a connection to a DB and then create, read, update or delete its data through a REST API. All of that in TypeScript.
FoalTS is a high-level Node.JS to quickly buil web apps in TypeScript. Why should you use it?
- It is natively written in TypeScript and aims to be used with this language with all its features.
- It is designed to fastly bootstrap and develop an application. Authentication, REST API, developing tools, you don't need to re-invent the wheel anymore while programming with Node.JS.
- Its architecture can support growing app espacially when it deals with structuring the code.

Let's get started!

## 1. Set up the Development Environment

Before starting anything, you need to set up your development environment. Using the `foal` generator is not mandatory but we recommand to use it since it will help you to start quickly.
Before starting anything, you need to set up your development environment.

First install [Node.Js and npm](https://nodejs.org/en/download/) if they are not already installed on your host.

Then install `yeoman` (generator manager) and the `foal` generator.
Then install the FoalTS command line interface `@foal/cli`.

```sh
npm install -g yo generator-foal
npm install -g @foal/cli
```

## 2. Create a new project
Expand All @@ -44,12 +47,12 @@ Go the project directory and start the server.

```sh
cd my-app
npm run dev:app
npm run develop
```

Open you browser on `http://localhost:3000` and find our welcoming message!

> `npm run dev:app` starts the **development server**. It watches at your files and automatically compiles and reloads your code. You don鈥檛 need to restart the server each time you make code changes. Note that it is only intended to be used in development, do not use it on production. <!-- See the [8. Build and deploy](./guide/8-build-and-deploy.md) section for more details. -->
> `npm run develop` starts the **development server**. It watches at your files and automatically compiles and reloads your code. You don鈥檛 need to restart the server each time you make code changes. Note that it is only intended to be used in development, do not use it on production. <!-- See the [8. Build and deploy](./guide/8-build-and-deploy.md) section for more details. -->
> **Port 3000 already in use?**
>
Expand Down
1 change: 0 additions & 1 deletion docs/guide/1-introduction.md
Expand Up @@ -5,7 +5,6 @@
This guide covers the basics of `FoalTS`. You will learn how to quickly build a web application using the core concepts of the framework.

For this example you are going to create a todo-app and be taught how to:
- set up a connection database,
- create a model service,
- serve a REST API,
- control input data,
Expand Down
28 changes: 13 additions & 15 deletions docs/guide/3-task-service.md
Expand Up @@ -2,23 +2,18 @@

Now that the database connection is set up, you can create a `Task` model service. This service aims to perform any CRUD operations (Create, Read, Update, Delete) to the `tasks` table.

Run `yo foal:service task` and choose `Sequelize model`.
Run `foal generate service task` and choose `Model service`.

Open the new created `task.service.ts` file. It shoud look like this:

```typescript
import { Service } from '@foal/core';
import { SequelizeModelService } from '@foal/sequelize';
import { ModelService, Service } from '@foal/core';

import { ConnectionService } from './connection.service';
import { Task } from './task.model';

@Service()
export class TaskService extends SequelizeModelService<any> {
constructor(protected connection: ConnectionService) {
super('tasks', {
// Schema
}, connection);
}
export class TaskService extends ModelService<Task> {
EntityClass = Task;
}

```
Expand All @@ -28,10 +23,13 @@ export class TaskService extends SequelizeModelService<any> {
Let's define the schema of our tasks. Import `Sequelize` from `@foal/sequelize` and update the second argument with the given fields:

```typescript
{
completed: { type: Sequelize.BOOLEAN, allowNull: false, defaultValue: false },
text: { type: Sequelize.STRING, allowNull: false, defaultValue: '' }
}
@Column({ default: false})
completed: boolean;

@Column()
text: string;
```

> *Note:* You can find more data types [here](http://docs.sequelizejs.com/manual/tutorial/models-definition.html).
Add to `initDB`.

> *Note:* You can find more data types [here](http://typeorm.io/#/entities/column-types-for-mysql--mariadb).
2 changes: 1 addition & 1 deletion docs/guide/4-rest-api-endpoint.md
Expand Up @@ -23,6 +23,6 @@ That's it! We now have a REST API at the endpoint `/tasks`. Go back to your brow

First we imported the controller factory `rest` from the `@foal/core` package. A controller factory creates controllers from services that implement a specific interface. For instance, the `rest` factory takes those which implement the `Partial<IModelService>` interface.

Once a controller is created (with the `attachService` method), it needs to be registered within a module. Every app starts with a module which in this case is the `AppModule`. That's all you need to know for the moment.
Once a controller is created, it needs to be registered within a module. Every app starts with a module which in this case is the `AppModule`. That's all you need to know for the moment.

Now take a time and look at your code. You ended setting up a REST API with just a few lines! No need to reinvent the wheel every time!
23 changes: 10 additions & 13 deletions docs/guide/6-add-a-logger.md
Expand Up @@ -26,22 +26,19 @@ class LoggerService {
Now go back to `task.service.ts`, import the `LoggerService`, add `public logger: LoggerService` to the constructor and extend the `createOne` method with some logging.

```typescript
import { Service } from '@foal/core';
import { Sequelize, SequelizeModelService } from '@foal/sequelize';

import { ConnectionService } from './connection.service';
import { LoggerService } from './logger.service';

import { ModelService, Service } from '@foal/core';

import { Task } from './task.model';

@Service()
export class TaskService extends SequelizeModelService<any> {
constructor(protected connection: ConnectionService, public logger: LoggerService) {
super('tasks', {
completed: { type: Sequelize.BOOLEAN, allowNull: false, defaultValue: false },
text: { type: Sequelize.STRING, allowNull: false, defaultValue: '' }
}, connection);
}
export class TaskService extends ModelService<Task> {
EntityClass = Task;

constructor(private logger: LoggerService) {}

createOne(data) {
createOne(record: Partial<Task>): Task {
this.logger.log('info', 'Create called with ' + JSON.stringify(data));
return super.create(data)
}
Expand All @@ -52,4 +49,4 @@ export class TaskService extends SequelizeModelService<any> {

Create a new task in the browser and then take a look at the terminal from where you launched the app. New logs should appear.

By writting `public logger: LoggerService` we injected the logger service in the task one. You don't need to instantiate the logger yourself, `FoalTS` takes care of it.
By writting `private logger: LoggerService` we injected the logger service in the task one. You don't need to instantiate the logger yourself, `FoalTS` takes care of it.
3 changes: 1 addition & 2 deletions docs/guide/7-test.md
Expand Up @@ -7,7 +7,6 @@ Before testing all your those you need to update `task.service.spec.ts` to take
```typescript
import { TaskService } from './task.service';

import { ConnectionService } from './connection.service';
import { LoggerService } from './logger.service';

describe('TaskService', () => {
Expand All @@ -17,7 +16,7 @@ describe('TaskService', () => {

it('should instantiate.', () => {
connection = new ConnectionService();
service = new TaskService(connection, new LoggerService());
service = new TaskService(new LoggerService());
});
});
```
Expand Down

0 comments on commit 41cc18d

Please sign in to comment.