Coder Social home page Coder Social logo

koa-ts-api's Introduction

koa-ts-api

Overview

Welcome to the documentation for the koa-ts-api project, showcasing the use of Koa, TypeScript, and TypeORM. This project serves as a template for building robust APIs with a modern, minimalistic stack.

It also provides use of Docker containers, in order to have the different parts separated (API, database).

PostgreSQL is selected as database storage.

There's also the possibility to use nodemon during development time, to make it easier for devs to try changes.

Table of Contents

Installation

To get started, follow these steps to install the project:

git clone https://github.com/pipetus/koa-ts-api.git
cd koa-ts-api
npm install

Configuration

Environment

There are a few environment variables that can be set to configure, provided in .env.sample.

These will be used in the API project itself:

APP_NAME=app-name # will be used as part of the container's names
DB_HOST=
DB_PORT=
DB_USER=
DB_PASSWORD=
DB_NAME=

These will be used in the database container:

# Postgres
POSTGRES_USER=
POSTGRES_PASSWORD=
PGUSER=
POSTGRES_DB=
POSTGRES_HOST=
POSTGRES_PORT=

Files

Configure the project by updating the necessary settings. Key configuration files include:

  • tsconfig.json: TypeScript compiler options.
  • src/database/datasource.ts: TypeORM configuration for database connection.

Usage

Boot

Start the server using:

npm dev

This will run the project in development mode. Visit http://localhost:3000 (or the port defined in the environment variable) to interact with the API.

Development conventions

Keeping in mind a basic workflow of creating and endpoint, supporting RESTful access, the code provided in this project follows these conventions:

  1. Create a router for the endpoint (src/app/routes/*.ts).
  2. Create a controller (src/app/controllers/*.ts) these are going to receive a custom router context.
  3. Perform logic using services (src/app/services/*.ts).
  4. Perform validations using validators (src/app/validators/*.ts) these are Joi objects used to validate body, params, query.
  5. Use models (src/app/models/*.ts); these are TypeORM Entities.
  6. Return data using serializers (src/app/serializers) these respond to JSON API format.
  7. Additionally, if needed, perform any model changes by means of migrations (src/database/migrations).
  8. Also, if needed, data can be pre-loaded by means of seeders (src/database/seeders).

Testing

Jest is used as the testing framework, along with a few additional libraries to perform some tasks such as creating objects via factories.

Keeping in mind the project's basic form, testing encouraged on:

  • Entities
  • Controllers: a sample is provided, following the approach of arrange (prepare the database and the context of a request), act (calling the actual action) and assert (perform expectation matching).
  • Requests: similar to controllers, only at API level.
  • Services

TODO

  • Handling of static content
  • Authorization
  • Client to communicate with other APIs

Acknowledgements

This project is heavily based on most of these ideas of Matt Chapman's.

koa-ts-api's People

Contributors

oscarbotteri avatar pipetus avatar

Watchers

 avatar

koa-ts-api's Issues

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.