DEV Community: Victor Teo

Write a backend server, and you get an Admin Dashboard for free!

Victor Teo — Thu, 16 May 2024 04:25:00 +0000

Teo is a great web framework, which can generate an Admin Dashboard for you.

In this article, I’ll show you how to write a simple backend server with Teo and have an Admin Dashboard generated for free.

Create a project

Let’s create a new directory, and in the directory, create a file named “schema.teo”. You may install this VSCode plugin for syntax highlighting and auto completion.

connector {
  provider: .sqlite,
  url: "sqlite:./database.sqlite",
}

server {
  bind: ("0.0.0.0", 5054)
}

admin {
  dest: "../hello-teo-admin-dashboard",
  host: .inject("process.env.TEO_HOST"),
  languages: [.enUs, .enUk, .de, .es, .fr, .he, .hi, .ja, .ko, .zhCn, .zhTw]
}

@identity.tokenIssuer($identity.jwt(expired: 3600 * 24 * 365))
@identity.jwtSecret(ENV["JWT_SECRET"]!) @admin.administrator
model Root {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  email: String
  @writeonly @onSet($presents.bcrypt.salt) @admin.secureInput
  @identity.checker($get(.value).presents.bcrypt.verify($self.get(.password).presents))
  password: String

  include handler identity.signIn
  include handler identity.identity
}

@identity.tokenIssuer($identity.jwt(expired: 3600 * 24 * 365))
@identity.jwtSecret(ENV["JWT_SECRET"]!) @admin.administrator
model Admin {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  email: String
  @unique @identity.id
  phoneNo: String
  @writeonly @onSet($presents.bcrypt.salt) @admin.secureInput
  @identity.checker($get(.value).presents.bcrypt.verify($self.get(.password).presents))
  password: String

  include handler identity.signIn
  include handler identity.identity
}

enum Sex {
  male
  female
}

model Record {
  @id @autoIncrement @readonly
  id: Int
  string: String
  bool: Bool
  int: Int
  float: Float
  decimal: Decimal
  date: Date
  dateTime: DateTime
  sex: Sex
}

model NullableRecord {
  @id @autoIncrement @readonly
  id: Int
  string: String?
  bool: Bool?
  int: Int?
  float: Float?
  decimal: Decimal?
  date: Date?
  dateTime: DateTime?
  sex: Sex?
}

middlewares [identity.identityFromJwt(secret: ENV["JWT_SECRET"]!)]

autoseed dataset default {
  group Admin {
    record admin {
      email: "admin@gmail.com",
      phoneNo: "13588888888",
      password: "Aa123456"
    }
  }
  group Root {
    record root {
      email: "root@gmail.com",
      password: "Aa123456"
    }
  }
}

The Teo schema language is quite descriptive and readable. In the schema, we declare these things:

How the HTTP server binds
To which database we are connect
Where do we generate our Admin Dashboard code
Authentication middlewares
Model definitions
Seeding data

We declared so many things in just 100 of lines. The syntax is very concise.

In the authentication middleware and model decorators, you will find an environment variable named “JWT_SECRET”. Let’s create a file named “.env” with this content.

JWT_SECRET=my_top_secret

Install Teo

Depends on your tech stack and preferences, you can install the Rust version, Node.js version or Python version. Choose one of these.

To install the Rust version, use “cargo”.

cargo install teo

To install the Node.js version, run these commands to install it to the local directory.

npm init -y
npm install typescript ts-node -D
npx tsc --init
npm install @teocloud/teo

To install the Python version, venv is recommended.

python3.12 -m venv .venv
source .venv/bin/activate
pip install teo

Teo is like any other web frameworks, you can write route handlers with programming code and access Teo’s ORM API. In this article, we’re not going to demonstrate that.

Generate the Admin Dashboard

After Teo is installed, run this command to generate the Admin Dashboard code. The Admin Dashboard is written with TypeScript and React. It’s fully customizable. Generated code and user extended code do not conflict.

Rust command:

cargo teo generate admin

Node.js command:

npx teo generate admin

Python command (with venv enabled):

teo generate admin

Start the server

Use teo serve command to start the server.

Rust command:

cargo teo serve

Node.js command:

npx teo serve

Python command (with venv enabled):

teo serve

Start the Admin Dashboard

Navigate to the directory that the Admin Dashboard is generated. Install dependencies and start the webpack server. You need to have Node.js install in the system.

npm install
npm start

Open localhost:9000 in the browser

The last thing is open the browser and see what we have got. These signing in credentials are:

Admin email: admin@gmail.com
Root email: root@gmail.com
Password: Aa123456

Choose one of the account to sign in.

Now you can list, create, update and delete the records. More features including charts, graphs and tables will be implemented later on.

Summary

If you like this, don’t forget to click a star in GitHub to give us an encouragement.

GitHub: https://github.com/teocloud/teo

Official website: https://teodev.io

We will continue to make it even better. And add more features into it to suit you need.

Implement user authentication with Node.js and Teo in 5 lines of code

Victor Teo — Sun, 17 Mar 2024 14:11:00 +0000

Teo is a schema-centered web framework for Node.js, Python and Rust. It’s very concise and declarative. In this article, we’re going to use the Node.js version.

Authentication is vital to modern server apps. Teo simplifies the implementation of authentication. Authentication includes handling user signing in sessions, generate and validate user’s API tokens.

Setup the project

To setup a project, install the dependencies and do programming language specific setups. In the first article in the series, we explained what each step does in this process. In this tutorial, we just include the command for pasting.

mkdir hello-teo-authentication
cd hello-teo-authentication
npm init -y
npm install typescript ts-node -D
npx tsc --init
npm install @teocloud/teo

Password

Let’s create a simple password authentication. Paste this into a new file named schema.teo.

connector {
  provider: .sqlite,
  url: "sqlite:./database.sqlite"
}

server {
  bind: ("0.0.0.0", 5052)
}

@identity.tokenIssuer($identity.jwt(expired: 3600 * 24 * 365))
@identity.jwtSecret(ENV["JWT_SECRET"]!)
model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  email: String
  @writeonly @onSet($presents.bcrypt.salt)
  @identity.checker($get(.value).presents.bcrypt.verify($self.get(.password).presents))
  password: String

  include handler identity.signIn
  include handler identity.identity
}

middlewares [identity.identityFromJwt(secret: ENV["JWT_SECRET"]!)]

Create a dot env file .env in the same directory.

JWT_SECRET=my_top_secret

Let’s explain the newly introduced decorators and pipeline items one by one.

The authentication functionalities reside in Teo’s std.identity namespace
@identity.id specifies which field is used to fetch the user
@identity.checker specifies which field is used to validate credentials and how to validate
@bcrypt.salt performs a Bcrypt salting transform
@bcrypt.verify verifies the input value against the stored one
@writeonly hides the field value from the output
@identity.tokenIssuer specifies which type of token it generates
$identity.jwt performs the JWT token generation
identity.identityFromJwt middleware decodes the JWT token and set the identity to the request
identity.signIn is the template which defines the signIn handler
identity.identity is the template which fetches the user information from the token in the header

Let’s start the server and perform a signIn request.

npx teo serve

Send this JSON input to /User/create to create a user.

{
  "create": {
    "email": "01@gmail.com",
    "password": "Aa123456"
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com"
  }
}

Send this JSON input to /User/signIn.

{
  "credentials": {
    "email": "01@gmail.com",
    "password": "Aa123456"
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com"
  },
  "meta": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6eyJpZCI6MX0sIm1vZGVsIjpbIlVzZXIiXSwiZXhwIjoxNzQyMTI0NDk2fQ.x2DSIpdnUeJtsUOGQsHlGksr29aF-CWog6X5LILxsOc"
  }
}

We’ve create a token from this user. If you intentionally type the password wrongly, an error response is returned.

Companion validations

Practically only something like username and pasword are not enough. A lot of websites and apps integrates some third party image authentications to prevent non-human access. As a framework, Teo doesn’t integrate with any service providers. Instead, it’s easy to integrate any third-party service or identity with Teo.
Replace the content of schema.teo with this.

connector {
  provider: .sqlite,
  url: "sqlite:./database.sqlite"
}

server {
  bind: ("0.0.0.0", 5052)
}

@identity.tokenIssuer($identity.jwt(expired: 3600 * 24 * 365))
@identity.jwtSecret(ENV["JWT_SECRET"]!)
model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  email: String
  @writeonly @onSet($presents.bcrypt.salt)
  @identity.checker(
    $do($get(.value).presents.bcrypt.verify($self.get(.password).presents))
    .do($get(.companions).presents.get(.imageAuthToken).presents))
  password: String
  @virtual @writeonly @identity.companion
  imageAuthToken: String?

  include handler identity.signIn
  include handler identity.identity
}

middlewares [identity.identityFromJwt(secret: ENV["JWT_SECRET"]!)]

We created a @identity.companion field which is @virtual. A virtual field isn't stored into the database. Companion values are present when checking and validating against the checker value. In this simple example, we just ensure the image auth token value exists.
Restart the server and send this JSON input to /User/signIn.

{
  "credentials": {
    "email": "01@gmail.com",
    "password": "Aa123456",
    "imageAuthToken": "anytoken"
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com"
  },
  "meta": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6eyJpZCI6MX0sIm1vZGVsIjpbIlVzZXIiXSwiZXhwIjoxNzQyMTI2MDIwfQ.7e3gXp5zA_h-Yk4ClUhjIIZLL4sLXAIFpE3CDzL_gzs"
  }
}

Without the image auth token, this signIn request would fail.

Custom expiration interval

The token expiration interval can be dynamic instead of static. Let’s try an example of frontend passed expiration interval. Replace the content of schema.teo with this.

connector {
  provider: .sqlite,
  url: "sqlite:./database.sqlite"
}

server {
  bind: ("0.0.0.0", 5052)
}

@identity.tokenIssuer($identity.jwt(expired: $get(.expired).presents))
@identity.jwtSecret(ENV["JWT_SECRET"]!)
model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  email: String
  @writeonly @onSet($presents.bcrypt.salt)
  @identity.checker(
    $do($get(.value).presents.bcrypt.verify($self.get(.password).presents))
    .do($get(.companions).presents.get(.imageAuthToken).presents))
  password: String
  @virtual @writeonly @identity.companion
  imageAuthToken: String?
  @virtual @writeonly @identity.companion
  expired: Int64?

  include handler identity.signIn
  include handler identity.identity
}

middlewares [identity.identityFromJwt(secret: ENV["JWT_SECRET"]!)]

Starts the server again and send this to /User/signIn.

{
  "credentials": {
    "email": "01@gmail.com",
    "password": "Aa123456",
    "imageAuthToken": "anytoken",
    "expired": 2
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com"
  },
  "meta": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6eyJpZCI6MX0sIm1vZGVsIjpbIlVzZXIiXSwiZXhwIjoxNzEwNTk4MjQ5fQ.Oz9O2rB-usonrdfzt8q75vr0biOf_C6Y3JIaf5O3MAE"
  }
}

Since this token is valid for 2 seconds, just paste the token to the header and send this empty JSON input to /User/identity.

Headers:

Authorization: Bearer #your token#

{ }

{
  "error": {
    "type": "Unauthorized",
    "message": "token expired"
  }
}

Blocked account

Practically accounts can be blocked from signing in. Implement account blocking is quite easy. Just tell us what does it mean by invalid account.

Replace the content of schema.teo with this.

connector {
  provider: .sqlite,
  url: "sqlite:./database.sqlite"
}

server {
  bind: ("0.0.0.0", 5052)
}

@identity.tokenIssuer($identity.jwt(expired: $get(.expired).presents))
@identity.jwtSecret(ENV["JWT_SECRET"]!)
@identity.validateAccount($get(.enabled).presents.eq(true))
model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  email: String
  @writeonly @onSet($presents.bcrypt.salt)
  @identity.checker(
    $do($get(.value).presents.bcrypt.verify($self.get(.password).presents))
    .do($get(.companions).presents.get(.imageAuthToken).presents))
  password: String
  @virtual @writeonly @identity.companion
  imageAuthToken: String?
  @virtual @writeonly @identity.companion
  expired: Int64?
  @migration(default: true)
  enabled: Bool

  include handler identity.signIn
  include handler identity.identity
}

middlewares [identity.identityFromJwt(secret: ENV["JWT_SECRET"]

Let’s disable the previously created account. Send this JSON input to /User/update.

{
  "where": {
    "id": 1
  },
  "update": {
 "enabled": false
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com",
    "enabled": false
  }
}

Now the signIn handler doesn't work for him and token authentication always failed.

Third-party integration

Teo provides an easy way for developers to integrate with third party identity services such as signing in with Google, Facebook. For China developers, this may be something like signing in with WeChat.

Update the the content of schema.teo with this.

connector {
  provider: .sqlite,
  url: "sqlite:./database.sqlite"
}

server {
  bind: ("0.0.0.0", 5052)
}

@identity.tokenIssuer($identity.jwt(expired: $get(.expired).presents))
@identity.jwtSecret(ENV["JWT_SECRET"]!)
@identity.validateAccount(
  $message($get(.enabled).presents.eq(true), "this account is blocked"))
model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  email: String
  @writeonly @onSet($presents.bcrypt.salt)
  @identity.checker(
    $do($get(.value).presents.bcrypt.verify($self.get(.password).presents))
    .do($get(.companions).presents.get(.imageAuthToken).presents))
  password: String
  @virtual @writeonly @identity.companion
  imageAuthToken: String?
  @virtual @writeonly @identity.companion
  expired: Int64?
  @migration(default: true) @default(true)
  enabled: Bool
  @identity.id @unique
  thirdPartyId: String?
  @virtual @writeonly @identity.checker($get(.value).presents.valid)
  thirdPartyToken: String?

  include handler identity.signIn
  include handler identity.identity
}

middlewares [identity.identityFromJwt(secret: ENV["JWT_SECRET"]!)]

Restart the server and let’s create a new account with third party account binded by sending this input to /User/create.

{
  "create": {
    "email": "02@gmail.com",
    "password": "Aa123456",
    "thirdPartyId": "myFacebookId",
    "thirdPartyToken": "myThirdPartyToken"
  }
}

{
  "data": {
    "id": 2,
    "email": "02@gmail.com",
    "enabled": true,
    "thirdPartyId": "myFacebookId"
  }
}

Now try signing in with the third party id and token. Send this input to /User/signIn.

{
  "credentials": {
    "thirdPartyId": "myFacebookId",
    "thirdPartyToken": "myFacebookToken",
    "expired": 99999999999
  }
}

{
  "data": {
    "id": 2,
    "email": "02@gmail.com",
    "enabled": true,
    "thirdPartyId": "myFacebookId"
  },
  "meta": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6eyJpZCI6Mn0sIm1vZGVsIjpbIlVzZXIiXSwiZXhwIjoxMDE3MTA2MDMwOTJ9.LcOzp8DFToXDQEBtu8jMtnQp-BndAazsTdBT2i4Mi3U"
  }
}

For the sake of simplicity, let’s just use $valid to make every third party token valid. In the next section, we'll demonstrate how to create a custom pipeline item to validate user's credential input.

Phone number and auth code

Let’s add some complexity by introducing phone number and auth code. Replace the content of schema.teo with this.

connector {
  provider: .sqlite,
  url: "sqlite:./database.sqlite"
}

server {
  bind: ("0.0.0.0", 5052)
}

entity {
  provider: .node,
  dest: "./entities"
}

declare pipeline item validateAuthCode<T>: T -> String

@identity.tokenIssuer($identity.jwt(expired: $get(.expired).presents))
@identity.jwtSecret(ENV["JWT_SECRET"]!)
@identity.validateAccount(
  $message($get(.enabled).presents.eq(true), "this account is blocked"))
model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail)) @identity.id
  @presentWithout(.phoneNumber)
  email: String?
  @writeonly @onSet($presents.bcrypt.salt)
  @identity.checker(
    $do($get(.value).presents.bcrypt.verify($self.get(.password).presents))
    .do($get(.companions).presents.get(.imageAuthToken).presents))
  password: String?
  @virtual @writeonly @identity.companion
  imageAuthToken: String?
  @virtual @writeonly @identity.companion
  expired: Int64?
  @migration(default: true) @default(true)
  enabled: Bool
  @identity.id @unique
  thirdPartyId: String?
  @virtual @writeonly @identity.checker($get(.value).presents.valid)
  thirdPartyToken: String?
  @onSet($if($presents, $regexMatch(/\\+?[0-9]+/))) @identity.id
  @presentWithout(.email) @unique
  phoneNumber: String?
  @virtual @writeonly @identity.checker($validateAuthCode)
  authCode: String?

  include handler identity.signIn
  include handler identity.identity
}

model AuthCode {
  @id @autoIncrement @readonly
  id: Int
  @presentWithout(.phoneNumber) @unique
  email: String?
  @presentWithout(.email) @unique
  phoneNumber: String?
  @onSave($randomDigits(4))
  code: String
}

middlewares [identity.identityFromJwt(secret: ENV["JWT_SECRET"]!)]

Generate entities for writing our custom pipeline item $validateAuthCode.

npx teo generate entity

Now let’s create main program file. Create a file named app.ts in the project directory.

import { App } from '@teocloud/teo'
import { AuthCodeWhereUniqueInput, Teo, User } from './entities'

const app = new App()

app.mainNamespace().defineValidatorPipelineItem(
    "validateAuthCode", 
    async (checkArgs: any, _, user: User, teo: Teo) => {
        const finder: AuthCodeWhereUniqueInput = {}
        if (checkArgs.ids.email) {
            finder.email = user.email!
        }
        if (checkArgs.ids.phoneNumber) {
            finder.phoneNumber = user.phoneNumber!
        }
        const authCode = await teo.authCode.findUnique({
            where: finder
        })
        if (!authCode) {
            return "auth code not found"
        }
        if (authCode.code !== checkArgs.value) {
            return "auth code is wrong"
        }
})

app.run()

Notice that we changed the type of email field from String to String?. For databases other than SQLite is all ok. However, SQLite disallows altering table columns. Using SQLite is for our demo purpose as it doesn't require installation. Just delete the database.sqlite file and let's have a new database setup.

Start the server with the updated command.

npx ts-node app.ts serve

Let’s recreate the previously created user. Send this to /User/create.

{
  "create": {
    "email": "01@gmail.com",
    "password": "Aa123456"
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com"
  }
}

Let’s send the auth code to this user. Send this JSON input to /AuthCode/create.

{
  "create": {
    "email": "01@gmail.com"
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com",
    "code": "8736"
  }
}

In practice, mark the code field with @writeonly to hide it from the output, and set an expire time.

Now try to sign in with this auth code. Send this to /User/signIn. Remember to replace the auth code with the one that you got.

{
  "credentials": {
    "email": "01@gmail.com",
    "authCode": "8736",
    "expired": 99999999999
  }
}

{
  "data": {
    "id": 1,
    "email": "01@gmail.com",
    "enabled": true
  },
  "meta": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6eyJpZCI6MX0sIm1vZGVsIjpbIlVzZXIiXSwiZXhwIjoxMDE3MTA2MTE5NDV9.dfO7oJ4Ka11ZfzLqjjxU2XMv83lq6qc1Ijv5WUSz5Ac"
  }
}

Now we can sign in with email and password, email and auth code, phone number with password, phone number with auth code. Together with the third party account bindings.

Teo 0.2.9 is published! Flutter client generation!

Victor Teo — Fri, 01 Mar 2024 14:47:00 +0000

Teo is a schema-centered next-generation web framework. It supports Node.js, Python and Rust. Teo transforms traditional CRUD development, aggregate & statistics API development and database migration into a single file with data model declarations. It increases development speed rapidly. Teo exposes ORM API, traditional route handlers and first-in-last-out middlewares for custom app logics. The route handlers are type-safe. Teo does data validations through the interfaces and models declared in the schema. It generates frontend clients from the schema for both auto-synthesized handlers and user-defined handlers.

Why Flutter client?

Actually in the version last year, Teo supports TypeScript/javaScript, Swift, Kotlin, C# and Dart client. Due to the big overhaul and the introduction of the namespace feature. The client generation code is not updated. This time, one of our user has requirement for this. We changed our plan and arranged this feature for him.
We care about business values. Having frontend developers write less code, is able to decrease development time and debugging time. For full-stack developers, these are just benefits of money and living quality. For companies and teams that choose and use Teo, this means lower cost and shorter development time.
Currently TypeScript/javaScript, and Dart/Flutter are supported. We never forgot clients of other languages. Flutter developers and teams build cross-platform products. We can help them more on reducing backend server development time. I love to help great people success. If I was rich, I would investigate a lot of great projects. It’s a pity that I’m poor. I love to create great open source frameworks, softwares and tools to make each of us living better. However, there isn’t any unemployment benefit in China, at least, it’s unavailable for me. What I can only do is creating great technical solutions. To save a lot of cost for users and make their business success, is like investigating without any shares. This is what I’m happy about.

Development plan

Currently we have an enterprise user and around 10 individual users. Our enterprise user want a feature which is generating the admin portal. We consider it quite makes sense. With this feature, developers don’t need to write any code or write a little code to obtain an admin portal. It provides visualization and interfaces for the server data. This feature is the next major task for us. We care our users and if you become our user, we takes your requirement into consideration and discuss with you for the best implementation. We may update our plan and add features just for you.

Next we will do:

Upgraded user session
Upgrated permission validation
Generating admin protal
Upgrated Swift client for Apple Vision Pro
Full-text search
Data subscription (for chatting softwares, games and online bidding softwares)
SQL JSON type and MongoDB nested interfaces
Support us

It’s been hard to create and maintain open source softwares. Hope you would click a star for us at Github.

Become our user

Wouldn’t it be nice if you become our user, and we are always responding fast if there are bugs found and requirements come. You can determine what we build next just for you. Our service is great and it’s totally free, most of the times better than paid ones. Join our Discord and we are available for you.

Become our contributor

I’d like to have more people discuss together, and develop together. I want sponsorships and fundings. But it’s ok if I don’t have that. Growing users and data are more important. If you could do anything to help, please contact me at yeannylam@gmail.com.

Write a schema only absolutely no code backend server with Node.js and Teo!

Victor Teo — Tue, 20 Feb 2024 21:46:00 +0000

Let's start with the simplest use case: Install Teo and start a schema only app. By the end of this tutorial, you gain understanding of how Teo schema composites and how to write them.

Installation

Install Node.js if it hasn't been installed. There are several ways to install Node.js. You may download the installer from the official website, or install it with tools like NVM. After installation, run this command to verify its installation.

node --version

v21.6.2

If you see some outputs like v21.6.2, great! Node.js is installed successfully.

Although now you can install Teo globally with the npm package manager. We highly recommand you to init a Node.js project and install Teo locally. This won't affect other projects that use Teo. To create a directory, init a
Node.js project, and install Teo, follow these commands.

mkdir hello-teo-schema-only
cd hello-teo-schema-only
npm init -y
npm install @teocloud/teo

Use the npx command to verify whether Teo is installed successfully.

npx teo --version

teo Teo 0.2.4 (Node.js v21.6.2) [CLI]

If you see this output, congratulations! And let's move on.

Editor plugin

We highly recommand you to use VSCode as we created
a plugin for syntax highlight, code diagnostics, auto completion and jump to definition.
Download our plugin from VSCode marketplace.

Write your first schema

In the current working directory, create a file named schema.teo.

touch schema.teo

Paste these content into the file.

connector {
  provider: .sqlite,
  url: "sqlite::memory:"
}

server {
  bind: ("0.0.0.0", 5050)
}

model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail))
  email: String
  name: String?
  @relation(fields: .id, references: .authorId)
  posts: Post[]
}

model Post {
  @id @autoIncrement @readonly
  id: Int
  title: String
  content: String?
  @default(false)
  published: Bool
  @foreignKey
  authorId: Int
  @relation(fields: .authorId, references: .id)
  author: User
}

Let's explain what this schema describes.

The connector block defines to which database this server connects. The content of the block is just a plain object literal with some predefined key value pairs. The expression starts with a . is enum variant literal in Teo schema. It's inspired by Apple's Swift programming language and is widely used in schema. The benefits of prefixing with a dot is that it's easy to write and
complete. Obviously, this server app connects to an in-memory SQLite database.
The server block defines how the server behaves. The syntax is the same with connector. These blocks are for configuration, and they are called config blocks in Teo. Guess what it does? The answer is that the server will listen at port 5050. The thing wrapped by a pair of parenthesis is tuple type. Teo supports a bunch of builtin types including ranges and tuples. Anyway, there are mostly used in config blocks.
The model keyword defines models. A model represents a database table and a set of auto synthesized HTTP requests to interact with it. The things start with a @ is called decorator. In Teo schema, plenty of things can be decorated including models, model fields, model relations. A decorator modifies the behavior of the decorated item. The thing start with a $ is called pipeline. There are one or more pipeline items in a pipeline. A pipeline validates and transforms its input value into its output value, or throw errors if value is invalid. Look at this part: $if($presents, $isEmail). It means when an email value is set, if the value is not null, which is presented, validate the value against $isEmail. If the value passed in is not a valid email address, revoke this value and throw an error to the frontend requester. The @relation decorator defines a model relation. In this case, a user has many posts and a post has an author. The fields argument and references argument takes 1 or more primitive fields on the model. These argument describes by which fields the models are connected. The trailing ? in a type expression indicates the value is optional.

In Teo schema, trailing comma is allowed wherever comma is used. The whole schema langauge is inspired by a lot of languages like TypeScript, Swift, GraphQL and Prisma.
When we design this, we want developers to feel familiar. We take advantages from different programming languages, combine them with our descriptive declarations. Teo schema is quite easy and not something to learn with. If you have trouble with understanding Teo schema, take it easy, join our Discord group, there
are people available to help you.

Add models with many-to-many relations

Append these code to the schema file.

model Artist {
  @id @autoIncrement @readonly
  id: Int
  name: String
  @relation(through: Perform, local: .artist, foreign: .song)
  songs: Song[]
}

model Song {
  @id @autoIncrement @readonly
  id: Int
  name: String
  @relation(through: Perform, local: .song, foreign: .artist)
  artists: Artist[]
}

@id([.songId, .artistId])
model Perform {
  @foreignKey
  artistId: Int
  @foreignKey
  songId: Int
  @relation(fields: .songId, references: .id)
  song: Song
  @relation(fields: .artistId, references: .id)
  artist: Artist
}

In Teo, unlike Ruby on Rails or Prisma, join table of a many-to-many relation is declared explicitly. In a many-to-many relation, @relation takes a join model and two direct relations defined on join model. It's quite clear to write everything out in such a short lines of code. Join tables sometimes is meaningful on their own. With it explicitly declared, database migration won't be hard when you are adding fields and contents to it. Notice the id of the model Perform is declared at the level of model. This is a compound primary key.

Run the server

Now run this command to start the server.

npx teo serve

[2023-12-20 04:58:40] sqlite connector connected for `main` at "sqlite::memory:"
[2023-12-20 04:58:40] Teo 0.2.4 (Node.js v21.6.2, CLI)
[2023-12-20 04:58:40] listening on port 5050

If you see the output likt above, congratulation, it starts successfully.
If it cannot start successfully, most of the times, the reason is the
database setup and configuration.

Now our server is ready to listen and handle requests.

Create request

Send this request body to /User/create.

{
  "create": {
    "email": "ada@teocloud.io",
    "name": "Ada",
    "posts": {
      "create": [
        {
          "title": "Introducing Teo",
          "content": "This post introduces Teo."
        },
        {
          "title": "The next generation framework",
          "content": "Use the next generation technology."
        }
      ]
    }
  },
  "include": {
    "posts": true
  }
}

{
  "data": {
    "id": 1,
    "email": "ada@teocloud.io",
    "name": "Ada",
    "posts": [
      {
        "id": 1,
        "title": "Introducing Teo",
        "content": "This post introduces Teo.",
        "published": false,
        "authorId": 1
      },
      {
        "id": 2,
        "title": "The next generation framework",
        "content": "Use the next generation technology.",
        "published": false,
        "authorId": 1
      }
    ]
  }
}

In this request, we've created a user with two related posts. If you request this again, you will get a unique constraint violation error. This is the designated behavior as we've declared email field of user to be @unique.

send again...

{
  "error": {
    "type": "ValueError",
    "message": "value is invalid",
    "fields": {
      "create": "unique value duplicated: email"
    }
  }
}

Send this request to /Artist/createMany.

{
  "create": [
    {
      "name": "Ed Sheeran",
      "songs": {
        "create": [
          {
            "name": "Perfect"
          },
          {
            "name": "Eyes Closed"
          }
        ]
      }
    },
    {
      "name": "Taylor Swift",
      "songs": {
        "create": [
          {
            "name": "Love Story"
          },
          {
            "name": "Red"
          }
        ]
      }
    }
  ],
  "include": {
    "songs": true
  }
}

{
  "data": [
    {
      "id": 1,
      "name": "Ed Sheeran",
      "songs": [
        {
          "id": 1,
          "name": "Perfect"
        },
        {
          "id": 2,
          "name": "Eyes Closed"
        }
      ]
    },
    {
      "id": 2,
      "name": "Taylor Swift",
      "songs": [
        {
          "id": 3,
          "name": "Love Story"
        },
        {
          "id": 4,
          "name": "Red"
        }
      ]
    }
  ],
  "meta": {
    "count": 2
  }
}

We created two artists with two songs each. In this request, instead of using create handler, we use createMany. With createMany, the arguments become an array of inputs. We can create many database records in a single batch. If any record creation failed, the transaction mechanism is triggered.

Find many request

Let's query what we've created before. Send this request body to /Song/findMany.

{
  "include": {
    "artists": {
      "select": {
        "name": true
      }
    }
  }
}

{
  "data": [
    {
      "id": 1,
      "name": "Perfect",
      "artists": [
        {
          "name": "Ed Sheeran"
        }
      ]
    },
    {
      "id": 2,
      "name": "Eyes Closed",
      "artists": [
        {
          "name": "Ed Sheeran"
        }
      ]
    },
    {
      "id": 3,
      "name": "Love Story",
      "artists": [
        {
          "name": "Taylor Swift"
        }
      ]
    },
    {
      "id": 4,
      "name": "Red",
      "artists": [
        {
          "name": "Taylor Swift"
        }
      ]
    }
  ],
  "meta": {
    "count": 4
  }
}

We limited the returned value with select. Only selected fields are returned. We can query further by specify some where conditions.

{
  "where": {
    "name": {
      "startsWith": "Perfect"
    }
  },
  "include": {
    "artists": {
      "where": {
        "name": "Not exist"
      },
      "select": {
        "name": true
      }
    }
  }
}

{
  "data": [
    {
      "id": 1,
      "name": "Perfect",
      "artists": []
    }
  ],
  "meta": {
    "count": 1
  }
}

In this request, only 1 song is returned. Although we include the artists in the response, the only artist that is related to the song is filtered out by a where condition.

Update requests

To perform a update request, combine where and update together in the request body and send it to /Song/update.

{
  "where": {
    "id": 1
  },
  "update": {
    "name": "Perfect Symphony",
    "artists": {
      "update": {
        "where": {
          "id": 1
        },
        "update": {
          "name": "Richard Clayderman"
        }
      }
    }
  },
  "include": {
    "artists": true
  }
}

{
  "data": {
    "id": 1,
    "name": "Perfect Symphony",
    "artists": [
      {
        "id": 1,
        "name": "Richard Clayderman"
      }
    ]
  }
}

We can nested update related records with Teo. If any update is invalid, it rollbacks.

Summary

There are a lot of builtin model route handlers including delete, upsert, copy, createMany, findFirst, findUnique and so on. Relation queries are supported except delete and deleteMany.

Hope it's not hard to catch up with us. Teo is quite easy and simple to use. Find us in our Discord group if you have any troubles.

In the next tutorial in this series, you'll learn how to write route handlers with Teo. Programming code is necessary to write custom business logics.