Forem: Warren Wong

Create Your Own AdonisJS Commands to Create and Drop Databases

Warren Wong — Thu, 12 Aug 2021 00:00:00 +0000

If you found yourself logging into psql every time you needed to just drop and create a database while building your AdonisJS project, I have good news for you.

AdonisJS allows you to write your own custom node ace scripts to make your development process much smoother.

First off, we'll be using the pgtools library to help us create and drop the database.

# npm
npm i -D pgtools

# yarn
yarn add -D pgtools

Now, create a new command for creating and dropping the database. Since there's already a db:seed, I think db:create and db:drop will be appropriate.

node ace make:commmand db:create
node ace make:command db:drop

These scripts will generate two new files, commands/dbCreate.ts and commands/dbDrop.ts.

To create a database, we'll use pgtools.createdb, which takes a config object as the first argument, and the database name as the second. The third argument will be a NodeJS style callback.

import { BaseCommand } from "@adonisjs/core/build/standalone";
import * as pgtools from "pgtools";

const config = {
  user: process.env.PG_USER,
  password: process.env.PG_PASSWORD,
  port: process.env.PG_PORT,
  host: process.env.PG_HOST,
};

const createDb = async () =>
  await new Promise<any>((resolve, reject) => {
    pgtools.createdb(config, process.env.PG_DB_NAME, (err, res) => {
      if (res) {
        resolve(res);
      }
      if (err) {
        reject(err);
      }
    });
  });

The config object uses our environment variables to populate the values. Rather than use the pgtools.createdb function directly, we'll wrap it in a Promise since generated run method of our DbCreate class uses the async/await syntax. I also want to pass through the err and res arguments so the logger can log out those messages.

export default class DbCreate extends BaseCommand {
  /**
   * Command name is used to run the command
   */
  public static commandName = "db:create";

  /**
   * Command description is displayed in the "help" output
   */
  public static description = "Create database";

  public static settings = {
    /**
     * Set the following value to true, if you want to load the application
     * before running the command
     */
    loadApp: true,

    /**
     * Set the following value to true, if you want this command to keep running until
     * you manually decide to exit the process
     */
    stayAlive: false,
  };

  public async run() {
    try {
      const res = await createDb();
      this.logger.info(res.command);
    } catch (err) {
      this.logger.error(err);
    }
  }
}

We need to change the loadApp property to true because we need to load the app so that we can use the environment variables available through the .env file.

Within the run method, we will wrap the call to createDb in a try/catch block. If anything goes wrong, I want to log out the error, if everything is fine, I want to log out the command property that pgtools.createdb returned.

We'll use the same approach with db:drop here as well:

import { BaseCommand } from "@adonisjs/core/build/standalone";
import * as pgtools from "pgtools";

const config = {
  user: process.env.PG_USER,
  password: process.env.PG_PASSWORD,
  port: process.env.PG_PORT,
  host: process.env.PG_HOST,
};

const dropDb = async () =>
  await new Promise<any>((resolve, reject) => {
    pgtools.dropdb(config, process.env.PG_DB_NAME, (err, res) => {
      if (res) {
        resolve(res);
      }
      if (err) {
        reject(err);
      }
    });
  });

export default class DbDrop extends BaseCommand {
  /**
   * Command name is used to run the command
   */
  public static commandName = "db:drop";

  /**
   * Command description is displayed in the "help" output
   */
  public static description = "Drop database";

  public static settings = {
    /**
     * Set the following value to true, if you want to load the application
     * before running the command
     */
    loadApp: true,

    /**
     * Set the following value to true, if you want this command to keep running until
     * you manually decide to exit the process
     */
    stayAlive: false,
  };

  public async run() {
    try {
      const res = await dropDb();
      this.logger.info(res.command);
    } catch (err) {
      this.logger.error(err);
    }
  }
}

After creating the commands, run:

node ace generate:manifest

This will create a JSON index of all available commands.

Now you can use node ace db:create to quickly create a database and node ace db:drop to quickly drop one.

Testing Authenticated Routes in AdonisJS

Warren Wong — Wed, 11 Aug 2021 00:00:00 +0000

If you haven't created an AdonisJS 5.0 app yet, you can check out my previous post or follow the docs here.

We'll be testing authenticated routes, so if you haven't added authentication to your AdonisJS project, take a look at Add Authentication to Your AdonisJS Project. For some background on the libraries used, check out this post Aman Virk wrote.

Set Up the Test Runner

So it's time to add tests to your brand new AdonisJS project, but what to do? AdonisJS doesn't come with a test-runner out-of-the-box at the moment. Well, for the most part, it's fairly simple if you just follow these simple steps.

First, install the dependencies:

# npm
npm i -D japa execa get-port supertest @types/supertest jsdom @types/jsdom

# yarn
yarn add -D japa execa get-port supertest @types/supertest jsdom @types/jsdom

Now, just copy japaFile.ts from the article here. We'll need to interact with the database so just copy it verbatim and place it at the base directory of the project:

import { HttpServer } from "@adonisjs/core/build/src/Ignitor/HttpServer";
import execa from "execa";
import getPort from "get-port";
import { configure } from "japa";
import { join } from "path";
import "reflect-metadata";
import sourceMapSupport from "source-map-support";

process.env.NODE_ENV = "testing";
process.env.ADONIS_ACE_CWD = join(__dirname);
sourceMapSupport.install({ handleUncaughtExceptions: false });

export let app: HttpServer;

async function runMigrations() {
  await execa.node("ace", ["migration:run"], {
    stdio: "inherit",
  });
}

async function rollbackMigrations() {
  await execa.node("ace", ["migration:rollback"], {
    stdio: "inherit",
  });
}

async function startHttpServer() {
  const { Ignitor } = await import("@adonisjs/core/build/src/Ignitor");
  process.env.PORT = String(await getPort());
  app = new Ignitor(__dirname).httpServer();
  await app.start();
}

async function stopHttpServer() {
  await app.close();
}

configure({
  files: ["test/**/*.spec.ts"],
  before: [runMigrations, startHttpServer],
  after: [stopHttpServer, rollbackMigrations],
});

To run the test, we'll create a test script in our package.json file:

{
  "scripts": {
    "test": "node -r @adonisjs/assembler/build/register japaFile.ts"
  }
}

When working locally, I like to have a different database for dev and testing. AdonisJS can read the .env.testing file when NODE_ENV=testing, which was set in the japaFile.ts file. The easiest thing to do is to copy the .env file and rename it to .env.testing. Then go and add _test to the end of the current database name you have for your dev environment.

...
PG_DB_NAME=todos_test

Since we configured our test runner to look in the test directory for any file with the .spec.ts extension, we can just place any file matching that pattern in the test directory, and we will run it with the npm test command.

Set Up the Authentication Secured Routes (To-dos)

As with any tutorial, we want to have a simple, but practical, example. Let's just use a Tt-do list app as an example. Let's go over what we want to do with our To-dos.

I want a user to be signed-in in order to create and/or update a todo. What good are todos if no one can see them? So let's allow anyone to look at the list of todos, as well as look at each individual todo. I don't think I want anyone to delete a todo, maybe just to change the status (Open, Completed, or Closed).

Let's leverage the generators to create the model, controller, and migration.

Let's `make:migration`

node ace make:migration todos

Let's add a name, a description, and a foreign key of user_id to our new table:

import BaseSchema from "@ioc:Adonis/Lucid/Schema";

export default class Todos extends BaseSchema {
  protected tableName = "todos";

  public async up() {
    this.schema.createTable(this.tableName, table => {
      table.increments("id");
      table.string("name").notNullable();
      table.text("description");

      table.integer("user_id").notNullable();

      /**
       * Uses timestamptz for PostgreSQL and DATETIME2 for MSSQL
       */
      table.timestamp("created_at", { useTz: true });
      table.timestamp("updated_at", { useTz: true });

      table.foreign("user_id").references("users_id");
    });
  }

  public async down() {
    this.schema.dropTable(this.tableName);
  }
}

Run the migration:

node ace migration:run

Let's `make:model`

node ace make:model Todo

We'll want to add the same 3 fields we added to our migration, but we'll also want to add a belongsTo relationship to our model linking the User through the creator property:

import { BaseModel, BelongsTo, belongsTo, column } from "@ioc:Adonis/Lucid/Orm";
import { DateTime } from "luxon";
import User from "App/Models/User";

export default class Todo extends BaseModel {
  @column({ isPrimary: true })
  public id: number;

  @column()
  public userId: number;

  @column()
  public name: string;

  @column()
  public description: string;

  @belongsTo(() => User)
  public creator: BelongsTo<typeof User>;

  @column.dateTime({ autoCreate: true })
  public createdAt: DateTime;

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  public updatedAt: DateTime;
}

Add the corresponding hasMany relationship to the User model now:

...
import Todo from "App/Models/Todo";

export default class User extends BaseModel {
  ...
  @hasMany(() => Todo)
  public todos: HasMany<typeof Todo>;
  ...
}

Let's `make:controller`

node ace make:controller Todo

Now let's add our new /todos path to the routes.ts file:

...
Route.resource("todos", "TodosController").except(["destroy"]).middleware({
  create: "auth",
  edit: "auth",
  store: "auth",
  update: "auth",
});

Here, we want a RESTful resource, except destroy. I also want the request to run through the "auth" middleware for the create, edit, store, and update resources. Basically, anyone can view index and show, but anything else will require authentication.

We can see a list of our new routes with the node ace list:routes command. It's handy that it show which routes require authentication. It also lists the route names (handy for redirecting the linking).

┌────────────┬────────────────────────────────────┬────────────────────────────┬────────────┬────────────────────────┐
│ Method     │ Route                              │ Handler                    │ Middleware │ Name                   │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /                                  │ Closure                    │            │ home                   │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /login                             │ SessionsController.create  │            │ login                  │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ POST       │ /login                             │ SessionsController.store   │            │                        │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ POST       │ /logout                            │ SessionsController.destroy │            │                        │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /register                          │ UsersController.create     │            │                        │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ POST       │ /register                          │ UsersController.store      │            │                        │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /users/:id                         │ UsersController.show       │            │ users.show             │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /todos                             │ TodosController.index      │            │ todos.index            │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /todos/create                      │ TodosController.create     │ auth       │ todos.create           │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ POST       │ /todos                             │ TodosController.store      │ auth       │ todos.store            │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /todos/:id                         │ TodosController.show       │            │ todos.show             │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ HEAD, GET  │ /todos/:id/edit                    │ TodosController.edit       │ auth       │ todos.edit             │
├────────────┼────────────────────────────────────┼────────────────────────────┼────────────┼────────────────────────┤
│ PUT, PATCH │ /todos/:id                         │ TodosController.update     │ auth       │ todos.update           │
└────────────┴────────────────────────────────────┴────────────────────────────┴────────────┴────────────────────────┘

Back to Our Tests

Let's create a new test file called test/functional/todos.spec.ts. While I normally just start writing tests as I they come to my head, that's probably not idea. For just a high level overview, I know I'd like to test the To-do features. So far, it's just creating, saving, editing, and updating. Also, I'd want to make sure I test that anyone can access the index and show routes, but only an authenticated user can see the others.

Testing "To-dos"

Todo list shows up at the index route.
Individual todo shows up a the show route.
Create a todo and check the show route to see if it exists.
Edit a todo and check the show route to see if the data is updated.
Navigate to the create route without logging in to test if we get redirected to the sign-in page.
Navigate to the edit route without loggin in to test if we get redirected to the sign-in page.

This should cover it for now. As always, feel free to add more if you feel like it.

Write the tests

Testing the `index` Route

Anyone should be able to view the list of todos. A good question to ask is what should someone see if there are no todos to see (the null state). Well, there should at least be a link to the create route to create a new todo. If there are todos, we should show them.

First, let's start off testing for a page to load when we go to the index route, /todos. I have an inkling that I will massively refactor this later, but let's just start out simple. No point in premature optimization, expecially if it turns out we need less tests than we think.

import supertest from "supertest";
import test from "japa";

const baseUrl = `http://${process.env.HOST}:${process.env.PORT}`;

test.group("Todos", () => {
  test("'index' should show a link to create a new todo", async assert => {
    await supertest(baseUrl).get("/todos").expect(200);
  });
});

Here we use the supertest library to see if we get a status of 200 back when we navigate to /todos. After running the test with npm test, it looks like we forgot to even open up our controller file.

Missing method "index" on "TodosController"
...
  ✖ 'index' should show a link to create a new todo
    Error: expected 200 "OK", got 500 "Internal Server Error"

Let's go a create that index method and the Edge template that goes along with it:

import { HttpContextContract } from "@ioc:Adonis/Core/HttpContext";

export default class TodosController {
  public async index({ view }: HttpContextContract) {
    return await view.render("todos/index");
  }
}

node ace make:view todos/index

@layout('layouts/default')

@section('body')
<a href="{{ route('todos.create') }}">Create Todo</a>
@endsection

Looks like we're passing the tests after adding this little bit of code. Red-green-refactor FTW!

Let's add some more to our test. I want to test for that link.

  test("'index' should show a link to create a new todo", async assert => {
    const { text } = await supertest(baseUrl).get("/todos").expect(200);
    const { document } = new JSDOM(text).window;
    const createTodosLink = document.querySelector("#create-todo");

    assert.exists(createTodosLink);
  });

Here I want to query the document for an element with the create-todos id. Once I put the id on my "Create Todo" link, I should be green again.

<a href="{{ route('todos.create') }}" id="create-todo">Create Todo</a>

Now comes time to actually persist some Todos in the database and test to see if we can see them on /todos. Let's just simply create 2 new todos and test for their existence on the page.

  test("'index' should show all todos created", async assert => {
    const items = ["Have lunch", "Grocery shopping"];
    items.forEach(async name => await Todo.create({ name }));

    const { text } = await supertest(baseUrl).get("/todos");

    assert.include(text, items[0]);
    assert.include(text, items[1]);
  });

This looks simple enough. Let's create 2 Todos, "Have lunch" and "Grocery shopping". Once these are saved, I should be able to navigate to /todos and see both. Since we're doing red-green-refactor, let's run our tests first to get our "red" before we try to turn it "green" by implementing our solution.

"uncaughtException" detected. Process will shutdown
    error: insert into "todos" ("created_at", "name", "updated_at") values ($1, $2, $3) returning "id" - null value in column "user_id" of relation "todos" violates not-null constraint

Oops, looks like we forgot to add a user_id to our Todo. Let's create a user first, then add these Todos as "related" to the User.

  test("'index' should show all todos created", async assert => {
    const items = ["Have lunch", "Grocery shopping"];

    const user = await User.create({ email: "alice@email.com", password: "password" });
    await user.related("todos").createMany([{ name: items[0] }, { name: items[1] }]);

    const { text } = await supertest(baseUrl).get("/todos");

    assert.include(text, items[0]);
    assert.include(text, items[1]);
  });

Okay, now we're still not passing, but we don't have that knarly "uncaughtException" anymore. Now let's render out our list of todos. To do that, we'll need to query for the list of all todos in the controller, and then pass it to our view.

import Todo from "App/Models/Todo";

export default class TodosController {
  public async index({ view }: HttpContextContract) {

    const todos = await Todo.all();

    return await view.render("todos/index", { todos });
  }
}

@section('body')

<ul>
  @each(todo in todos)
  <li>{{ todo.name }}</li>
  @endeach
</ul>

<a href="{{ route('todos.create') }}" id="create-todo">Create Todo</a>
@endsection

Awesome. Back to "green".

Now let's work on the show route. We should be able to navigate there once the todo has been created.

test.group("Todos", () => {
  ...
  test("'show' should show the todo details", async assert => {
    const user = await User.create({ email: "alice@email.com", password: "password" });
    const todo = await user
      .related("todos")
      .create({ name: "Buy shoes", description: "Air Jordan 1" });
    const { text } = await supertest(baseUrl).get(`/todos/${todo.id}`);

    assert.include(text, todo.name);
    assert.include(text, todo.description);
  });
});

We're flying now. Our tests seem to have a lot of similar setup code. Possible refactor candidate. I'll note that for later.

export default class TodosController {
  ...
  public async show({ params, view }: HttpContextContract) {
    const id = params["id"];
    const todo = await Todo.findOrFail(id);
    return await view.render("todos/show", { todo });
  }
}

As with the index route, we'll need to create the view for our show route:

node ace make:view todos/show

@layout('layouts/default')

@section('body')
<h1>{{ todo.name }}</h1>
<p>{{ todo.description }}</p>
@endsection

Great, let's run the tests to see where we're at.

  ✖ 'show' should show the todo details
    error: insert into "users" ("created_at", "email", "password", "updated_at") values ($1, $2, $3, $4) returning "id" - duplicate key value violates unique constraint "users_email_unique"

Okay, you might have already thought, why's this guy creating another User with the same email? Well, what if I created this user in a test that's at the bottom of the file separated by hundreds of lines? What if the user was created for a test in another file? It would be really hard if we had to depend on some database state created who knows where.

Let's make sure we start each test, as if the database were brand new. Let's add some setup and teardown code:

test.group("Todos", group => {
  group.beforeEach(async () => {
    await Database.beginGlobalTransaction();
  });

  group.afterEach(async () => {
    await Database.rollbackGlobalTransaction();
  });
  ...
});

Alright! Back to green. So far, we've knocked off 2 tests from our "Testing todos" list we wrote before we started all the testing work.

Now it's time to tackle the create and update tests. Let's start it off like we started the others, with a test. Let's turn our "green" tests back to "red".

  test("'create' should 'store' a new `Todo` in the database", async assert => {
    const { text } = await supertest(baseUrl).get("/todos/create").expect(200);
    const { document } = new JSDOM(text).window;
    const createTodoForm = document.querySelector("#create-todo-form");

    assert.exists(createTodoForm);
  });

  ✖ 'create' should 'store' a new `Todo` in the database
    Error: expected 200 "OK", got 302 "Found"

Ahh, there we go. Our first issue with authentication. We need to be signed in to view this route, but how can we do that? After some Googling, looks like the supertest library has our solution. supertest allows you to access superagent, which will retain the session cookies between requests, so we'll just need to "register" a new user prior to visiting the store route.

  test("'create' should 'store' a new `Todo` in the database", async assert => {
    const agent = supertest.agent(baseUrl);
    await User.create({ email: "alice@email.com", password: "password" });
    await agent
      .post("/login")
      .field("email", "alice@email.com")
      .field("password", "password");
    const { text } = await agent.get("/todos/create").expect(200);
    const { document } = new JSDOM(text).window;
    const createTodoForm = document.querySelector("#create-todo-form");

    assert.exists(createTodoForm);
  });

export default class TodosController {
  ...
  public async create({ view }: HttpContextContract) {
    return await view.render("todos/create");
  }
}

node ace make:view todos/create

@layout('layouts/default')

@section('body')
<form action="{{ route('todos.store') }}" method="post" id="create-todo-form">
  <div>
    <label for="name"></label>
    <input type="text" name="name" id="name">
  </div>
  <div>
    <label for="description"></label>
    <textarea name="description" id="description" cols="30" rows="10"></textarea>
  </div>
</form>
@endsection

We really are flying now. By adding the form with the id of create-todo-form, we're passing our tests again. We've checked that the form is there, but does it work? That's the real question. And from the experience of signing the user in with supertest.agent, we know that we just need to post to the store route with fields of name and description.

  test("'create' should 'store' a new `Todo` in the database", async assert => {
    ...
    await agent
      .post("/todos")
      .field("name", "Clean room")
      .field("description", "It's filthy!");
    const todo = await Todo.findBy("name", "Clean room");
    assert.exists(todo);
  });

Okay, back to "red" with a missing store method on TodosController. By now, you don't even need to read the error message and you'll know what to do. But still, it's nice to run the tests at every step so you only work on the smallest bits to get your tests to turn back "green".

import Todo, { todoSchema } from "App/Models/Todo";
...
export default class TodosController {
  ...
  public async store({
    auth,
    request,
    response,
    session,
  }: HttpContextContract) {
    const { user } = auth;
    if (user) {
      const payload = await request.validate({ schema: todoSchema });
      const todo = await user.related("todos").create(payload);
      response.redirect().toRoute("todos.show", { id: todo.id });
    } else {
      session.flash({ warning: "Something went wrong." });
      response.redirect().toRoute("login");
    }
  }
}

import { schema } from "@ioc:Adonis/Core/Validator";
...
export const todoSchema = schema.create({
  name: schema.string({ trim: true }),
  description: schema.string(),
});

We're doing a little more with this one. First off, the signed in user is already exists in the context of the application and is accessible through the auth property. I created a schema called todoSchema which is used to validate the data passed from the form. This does 2 things that I don't have to worry about explicitly, if there are any errors, those errors will be available from flashMessages upon the next view render (which will be the create form). The resulting payload can be used directly to create the new Todo.

If, for some reason, I don't find the signed in user from auth, I can flash a warning message and redirect the user back to the login screen.

Now let's test our edit route. Since I had to sign for this test as well, I extracted that functionality to a helper function called loginUser. agent retains the session cookies and the User is returned to use to associate the newly created Todo. I update the name and description of the Todo then navigate to the show route and make sure the updated values exist on the page.

test.group("Todos", group => {
  ...
  test("'edit' should 'update' an existing `Todo` in the database", async assert => {
    const user = await loginUser(agent);
    const todo = await user.related("todos").create({
      name: "See dentist",
      description: "Root canal",
    });
    await agent.get(`/todos/${todo.id}/edit`).expect(200);
    await agent
      .put(`/todos/${todo.id}`)
      .field("name", "See movie")
      .field("name", "Horror flick!");
    const { text } = await agent.get(`/todos/${todo.id}`).expect(200);
    assert.include(text, "See movie");
    assert.include(text, "Horror flick!");
  });
});

async function loginUser(agent: supertest.SuperAgentTest) {
  const user = await User.create({
    email: "alice@email.com",
    password: "password",
  });
  await agent
    .post("/login")
    .field("email", "alice@email.com")
    .field("password", "password");
  return user;
}

As with the create test, the edit should show a form, but prepopulated with the current values. For now, let's just copy the todos/create view template for todos/edit. We'll need to update the values of the input and textarea elements with the current values.

export default class TodosController {
  ...
  public async edit({ params, view }: HttpContextContract) {
    const id = params["id"];
    const todo = Todo.findOrFail(id);
    return await view.render("todos/edit", { todo });
  }
}

node ace make:view todos/edit

@layout('layouts/default')

@section('body')
<form action="{{ route('todos.update', {id: todo.id}, {qs: {_method: 'put'}}) }}" method="post" id="edit-todo-form">
  <div>
    <label for="name"></label>
    <input type="text" name="name" id="name" value="{{ flashMessages.get('name') || todo.name }}">
  </div>
  <div>
    <label for="description"></label>
    <textarea name="description" id="description" cols="30" rows="10">
      {{ flashMessages.get('description') || todo.description }}
    </textarea>
  </div>
  <div>
    <input type="submit" value="Create">
  </div>
</form>
@endsection

Here we need to do some method spoofing, thus you see the strange action. This is just a way for AdonisJS spoof PUT, since HTTP only has GET and POST. You'll have to go to the app.ts file and set allowMethodSpoofing to true.

export const http: ServerConfig = {
  ...
  allowMethodSpoofing: true,
  ...
}

  public async update({ params, request, response }: HttpContextContract) {
    const id = params["id"];
    const payload = await request.validate({ schema: todoSchema });
    const todo = await Todo.updateOrCreate({ id }, payload);
    response.redirect().toRoute("todos.show", { id: todo.id });
  }

The last 2 tests we need to write are to check that going to create or edit redirects us to the sign-in page. There isn't any implementation since these are already done, but the negative case test is nice to have in case something breaks in the future.

  test("unauthenticated user to 'create' should redirect to signin", async assert => {
    const response = await agent.get("/todos/create").expect(302);
    assert.equal(response.headers.location, "/login");
  });

  test("unauthenticated user to 'edit' should redirect to signin", async assert => {
    const user = await User.create({
      email: "bob@email.com",
      password: "password",
    });
    const todo = await user.related("todos").create({ name: "Go hiking" });
    const response = await agent.get(`/todos/${todo.id}/edit`).expect(302);
    assert.equal(response.headers.location, "/login");
  });

These should both pass immediately. And now we're "green". We hit all the test cases we initially wanted to write, but our job is far from over. There's a fair bit of refactoring that needs to be done, not in the production code, but in the tests. If you see your tests as "documentation of intent", then there is definitely more editing to make things more clear.

While we're not done, this is a good place to stop. We've completed a feature. We have completed the tests we initially set out to write. We cycled between "red" and "green" several times. Now it's your turn. Are there any more tests you think you'd need to write. How about some refactoring?

Testing Authenticated Routes in Phoenix

Warren Wong — Wed, 04 Aug 2021 00:00:00 +0000

This will be a quick one, but it was tough for me to find.

Just some background: I used phx_gen_auth for authentication in my app. This little tidbit is going to play an important role in my "no duh" moment.

After using phx.gen.html or phx.gen.live to do some heavy lifting, Phoenix is nice enough to write out some tests for me as well.

Only problem is when I require an authenticated user for a certain route or resource. My nicely passing out-of-the-box tests no longer pass.

Well, jumping into the code, I just started by fixing one test at a time. I looked in the user_session_controller_test.exs file generated from running phx.gen.auth and found how they created the user:

import MyAwesomeProject.AccountsFixtures

setup do
  %{user: user_fixture()}
end

Okay, great! That means I can easily run user_fixture() to create a user and pass it into each test.

I then looked how the user was logged in in the test:

test "redirects if already logged in", %{conn: conn, user: user} do
  conn = conn
  |> log_in_user(user)
  |> get(Routes.user_session_path(conn, :new))
  assert redirected_to(conn) == "/"
end

Okay, simple enough. There's nice conveniently named function called log_in_user/2 that takes conn and user as parameters. Nice. I can do that on each of my tests too. But wait, that's not very DRY at all. Well, let's not even pass in the user to each test when I can just pass in an updated conn after logging in the user with log_in_user/2.

defp log_in_user(%{conn: conn}) do
  %{conn: log_in_user(conn, user_fixture())}
end

...

describe "MyAwesomeTest" do
  setup [:log_in_user]
  ...

But wait, where did log_in_user/2 come from. I had just made an assumption that it came from my import of MyAwesomeProject.AccountsFixtures. It actually came from MyAwesomeProject.ConnCase. It's that phx.gen.auth magic at work again!

And you know what I found when I just looked around in conn_case.exs?

@doc """
Setup helper that registers and logs in users.

    setup :register_and_log_in_user

It stores an updated connection and a registered user in the
test context.
"""
def register_and_log_in_user(%{conn: conn}) do
  user = GrokTheGreeks.AccountsFixtures.user_fixture()
  %{conn: log_in_user(conn, user), user: user}
end

I've never been happier knowing I wasted my time writing throw-away code.

Add Authentication to Your AdonisJS Project

Warren Wong — Wed, 07 Apr 2021 00:00:00 +0000

If you haven't created an AdonisJS 5.0 app yet, you can check out my previous post or follow the docs here.

Coming from the JavaScript/NodeJS world, I'm pretty used to having to pick off the npm menu for all the libraries I need, which then becomes a curation problem. With AdonisJS, there is usually a library already there for you to use to add in the common functionality you'd expect from any MVC framework.

First, we should install all the dependencies then run the invoke script for each of these libraries:

# npm
npm i @adonisjs/auth@alpha @adonisjs/session@alpha

# yarn
yarn add @adonisjs/auth@alpha @adonisjs/session@alpha

node ace invoke @adonisjs/auth
node ace invoke @adonisjs/session

Select the appropriate options for your project. You can see my choices below.

❯ Select provider for finding users · lucid
❯ Select which guard you need for authentication (select using space) · web
❯ Enter model name to be used for authentication · User
❯ Create migration for the users table? (y/N) · true
CREATE: app/Models/User.ts
CREATE: database/migrations/1587988332388_users.ts
CREATE: contracts/auth.ts
CREATE: config/auth.ts
CREATE: app/Middleware/Auth.ts
CREATE: app/Middleware/SilentAuth.ts
UPDATE: tsconfig.json { types += "@adonisjs/auth" }
UPDATE: .adonisrc.json { providers += "@adonisjs/auth" }
CREATE: ace-manifest.json file

I don't currently have a User model for this project, so running the invoke script will create it for me.

If you haven't already done so, install @adonisjs/lucid as well:

# npm
npm i @adonisjs/lucid@alpha

yarn add @adonisjs/lucid@alpha

Run the invoke script like you did for the other libraries:

node ace invoke @adonisjs/lucid

You will be prompted to select which database to use. I'll use PostgreSQL for this example, but feel free to use any you'd like. There shouldn't be any differences for this example.

At this point, you'll have to update your .env file to reflect your setup:

PORT=3333
HOST=0.0.0.0
NODE_ENV=development
APP_KEY=...
SESSION_DRIVER=cookie
CACHE_VIEWS=false
DB_CONNECTION=pg
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=postgres
PG_DB_NAME=example_app_dev

On my local machine, my PG_USER and PG_PASSWORD are the same: "postgres". Make sure to update the PG_DB_NAME as well, since the invoke script defaults that variable to "lucid". Here I use "example_app_dev".

Now if you haven't already, create a database that matches the PG_DB_NAME variable you have in your .env file. You can do that with the command line or with something like pgAdmin 4:

psql -U postgres

CREATE DATABASE example_app_dev;
\q

Now run the migration created earlier:

node ace migration:run

If you navigate to the newly created User model, you can what was created for us:

// app/Models/User.ts

import { DateTime } from "luxon";
import Hash from "@ioc:Adonis/Core/Hash";
import { column, beforeSave, BaseModel } from "@ioc:Adonis/Lucid/Orm";

export default class User extends BaseModel {
  @column({ isPrimary: true })
  public id: number;

  @column()
  public email: string;

  @column({ serializeAs: null })
  public password: string;

  @column()
  public rememberMeToken?: string;

  @column.dateTime({ autoCreate: true })
  public createdAt: DateTime;

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  public updatedAt: DateTime;

  @beforeSave()
  public static async hashPassword(user: User) {
    if (user.$dirty.password) {
      user.password = await Hash.make(user.password);
    }
  }
}

If you've used any Active Record type ORM before, everything should look familiar. There's a couple things I just wanted to point out though. The password column has an option of {serializeAs: null}, which makes it simple to deliver the User model to JSON using the serialize method on the model. You can alias that field in the JSON with serializeAs, but if you set it to null, that field won't show up, which is what we want with the password field.

Another thing I'd like to point out is the beforeSave decorator. This hook is invoked before insert and update queries, which is an obvious place to hash a password. Another interesting thing is the $dirty property on the model. Basically, we only want to hash a new or updated password. If that particular property hasn't changed, we should do nothing.

Now comes to something that can be a gotcha with the documentation. We are calling Hash from the @ioc:Adonis/Core/Hash module. It's nice that this is already a dependency, but what might confuse you is that you'll also have to select your own hashing library. If you run the migration at this point, nothing will be amiss until you try to actually hash a password. So let's avoid that and install the argon2 dependency for this module:

# npm
npm install phc-argon2

# yarn
yarn add phc-argon2

To add to the confusion, the phc-argon2 library itself is a fork of @phc/argon2, which is no longer maintained. You would have had to find the release notes to figure this out.

At this point you can follow the official docs because the out of the box experience is already pretty good. But if you want to keep following along for a more customized approach, please do.

If you open up the app/Middleware/Auth.ts file, you'll see the user will be redirected to the /login route if unauthenticated. I'm pretty partial to using the words "signin", "signout", and "signup" instead of "login", "logout", and "register", so that's what I'm going to do.

// app/Middleware/Auth.ts

export default class AuthMiddleware {
  /**
   * The URL to redirect to when request is Unauthorized
   */
  protected redirectTo = "/signin";
  ...

Now let's open up the start/routes.ts file and add our new routes:

// start/routes.ts

import Route from "@ioc:Adonis/Core/Route";

Route.on("/signin").render("signin");
Route.post("/signin", "AuthController.signin");
Route.on("/signup").render("signup");
Route.post("/signup", "AuthController.signup");
Route.post("/signout", "AuthController.signout");

Route.on("/").render("welcome");

As you can see, we'll need to create some views and a controller:

node ace make:view signin
node ace make:view signup
node ace make:controller Auth

If you already have TailwindCSS installed in your project, great! We'll be using Tailwind to design out signin and signup views. If not, let's bring it in to our project from the CDN. If you don't already have a layout edge template, create one now:

node ace make:view layouts/default

Now open up default.edge and add in our default HTML with our TailwindCSS dependency from CDN:

<!-- resources/views/layouts/default.edge -->
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">
  <title>Example App</title>
</head>

<body>
  @!section('content')
</body>

</html>

Now let's open up resources/views/signup.edge. Since I anticipate the signup and signin views will be rather similar, we can just create the signup view then copy it to signin.edge and remove the password confirmation section. We can also create a partial or component, but seeing as we're only using this particular form twice, I don't feel too bad about the duplication. There's going to be enough of a difference between the two templates that doesn't seem to make the work of generalizing the template worth it. You can, of course, do this on your own.

<!-- resources/views/signup.edge -->

@layout('layouts/default')

@section('content')
<div class="min-h-screen flex flex-col justify-center bg-gray-200 p-8">
  <div class="mx-auto bg-white px-8 py-6 shadow rounded-lg">
    <form action="{{ route('AuthController.signup') }}" method="post" class="space-y-8">
      <div>
        <label for="email" class="block text-gray-600">Email</label>
        <input type="text" name="email" value="{{ flashMessages.get('email') || '' }}"
          class="w-full px-3 py-2 border border-gray-300 rounded" />
        <p>{{ flashMessages.get('errors.email') || '' }}</p>
      </div>

      <div>
        <label for="password" class="block text-gray-600">Password</label>
        <input type="password" name="password" class="w-full px-3 py-2 border border-gray-300 rounded" />
        <p>{{ flashMessages.get('errors.password') || '' }}</p>
      </div>

      <div>
        <label for="password_confirmation" class="block text-gray-600">Re-Enter Password</label>
        <input type="password" name="password_confirmation" class="w-full px-3 py-2 border border-gray-300 rounded" />
        <p>{{ flashMessages.get('errors.password_confirmation') || '' }}</p>
      </div>

      <div>
        <button type="submit" class="w-full flex justify-center px-3 py-2 text-white bg-blue-600 rounded">Create
          Account</button>
      </div>
    </form>
  </div>
</div>
@endsection

Now let's copy this file to resources/views/signin.edge, but there's one change we need to make. We need to remove the password_confirmation field and replace it with a remember_me checkbox.

<!-- resources/views/signin.edge -->

@layout('layouts/default')

@section('content')
<div class="min-h-screen flex flex-col justify-center bg-gray-200 p-8">
  <div class="mx-auto bg-white px-8 py-6 shadow rounded-lg">
    <form action="{{ route('AuthController.signup') }}" method="post" class="space-y-8">
      <div>
        <label for="email" class="block text-gray-600">Email</label>
        <input type="text" name="email" value="{{ flashMessages.get('email') || '' }}"
          class="w-full px-3 py-2 border border-gray-300 rounded" />
        <p>{{ flashMessages.get('errors.email') || '' }}</p>
      </div>

      <div>
        <label for="password" class="block text-gray-600">Password</label>
        <input type="password" name="password" class="w-full px-3 py-2 border border-gray-300 rounded" />
        <p>{{ flashMessages.get('errors.password') || '' }}</p>
      </div>

      <div class="flex items-center">
        <input type="checkbox" name="remember_me" class="h-4 w-4 border-gray-300 rounded">
        <label for="remember_me" class="ml-2 text-sm text-gray-600">
          Remember me
        </label>
      </div>

      <div>
        <button type="submit" class="w-full flex justify-center px-3 py-2 text-white bg-blue-600 rounded">Create
          Account</button>
      </div>
    </form>
  </div>
</div>
@endsection

Now that we have our views, let's open the AuthController and add the "post" methods signin, signup, and signout. Let's just redirect to the index route for the moment.

// app/Controllers/Http/AuthController.ts

import { HttpContextContract } from "@ioc:Adonis/Core/HttpContext";

export default class AuthController {
  public signup({ response }: HttpContextContract) {
    // 1. Validate request

    return response.redirect("/");
  }

  public signin({ response }: HttpContextContract) {
    return response.redirect("/");
  }

  public signout({ response }: HttpContextContract) {
    return response.redirect("/");
  }
}

Now, I already know something about my app. I want to validate my form data before I persist my user in the database. I can do all that from the controller, but that just doesn't seem like the right place for all that logic. For a simple app like ours (so far), there's no problem writing everything in the controller. I could place all this logic in the model by adding some extra helper methods, but that's probably not a great approach either since we want to keep our models lean. I want to put all my "account" management business logic in a single place from which I can access my User model. I'll create a file at app/Account/index.ts.

// app/Account/index.ts

import User from "App/Models/User";
import { rules, schema } from "@ioc:Adonis/Core/Validator";

export const validationSchema = schema.create({
  email: schema.string({ trim: true }, [
    rules.email(),
    rules.unique({ table: "users", column: "email" }),
  ]),
  password: schema.string({ trim: true }, [rules.confirmed()]),
});

export const createUser = async (email: string, password: string) => {
  const user = new User();
  user.email = email;
  user.password = password;

  return await user.save();
};

Here we created a validationSchema to be used by the request.validate method in the AuthController. It simply checked to see if the string passed in to the "email" input is in the form of an email and that it does not already exist in the users table. The password is checked to have a matching value in the "password_confirmation" input with the rules.confirmed() rule.

If there's any errors, they will show in the paragraph element under the form inputs.

// app/Controllers/Http/AuthController.ts

...
export default class AuthController {
  public async signup({ request, response }: HttpContextContract) {
    const userDetails = await request.validate({ schema: validationSchema });
    const user = await createUser(userDetails.email, userDetails.password);
    return response.json(user.serialize());
  }
  ...
}

You can test this out by running our local server and navigating to http://localhost:3333:

You should see the serialized JSON output if the signup was successful:

{
  "email": "me@warrenwong.org",
  "created_at": "2021-04-07T15:02:51.730+08:00",
  "updated_at": "2021-04-07T15:02:51.754+08:00",
  "id": 1
}

Now that we can sign up, let's create a protected route that will redirect to the /signin page if unauthenticated. Let's go back to our routes and create a route at /dashboard that shows all our users.

// start/routes.ts

...
import { getUsers } from "App/Account";

Route.get("/dashboard", async ({ view }) => {
  const users = await getUsers();
  return view.render("dashboard", { users });
}).middleware("auth");

This assumes we have an exported function in our App/Account module that returns the users. The users are then passed into the Edge template as users.

// app/Account/index.ts

...
export const getUsers = async () => await User.all();

Create the dashboard view:

node ace make:view dashboard

Now we need to open start/kernel.ts and register our Auth middleware. You can name this anything, but "auth" seems like a decent default for this. Just make sure that the name you pick also matches the parameter passed to the middleware method in your routes.

// start/kernel.ts

...
Server.middleware.registerNamed({
  auth: "App/Middleware/Auth",
});

Now let's work on our dashboard before we get any further. We don't have too much data to display, but we may in the future, so let's anticipate that by displaying a nice table:

<!-- resources/views/dashboard.edge -->

@layout('layouts/default')

@section('content')
<div class="min-h-screen flex flex-col">
  <div class="m-16">
    <div class="shadow border-b border-gray-300 rounded-lg">
      <table class="min-w-full divide-y divide-gray-300">
        <thead class="bg-gray-50 text-left">
          <tr>
            <th class="px-6 py-4 text-gray-700">
              ID
            </th>
            <th class="px-6 py-4 text-gray-700">
              Email
            </th>
            <th class="px-6 py-4 text-gray-700">
              Created
            </th>
            <th class="px-6 py-4 text-gray-700">
              Updated
            </th>
          </tr>
        </thead>
        <tbody class="bg-white">
          @each(user in users)            
          <tr>
            <td class="px-6 py-4 text-gray-600">
              {{ user.id }}
            </td>
            <td class="px-6 py-4 text-gray-600">
              {{ user.email }}
            </td>
            <td class="px-6 py-4 text-gray-600">
              {{ user.createdAt }}
            </td>
            <td class="px-6 py-4 text-gray-600">
              {{ user.updatedAt }}
            </td>
          </tr>
          @endeach
        </tbody>
      </table>
    </div>
  </div>
</div>
@endsection

Now let's update the Auth controller to redirect to the dashboard whenever we've authenticated.

export default class AuthController {
  public async signup({ auth, request, response }: HttpContextContract) {
    const userDetails = await request.validate({ schema: validationSchema });
    const user = await createUser(userDetails.email, userDetails.password);
    await auth.login(user);
    return response.redirect("/dashboard");
  }
  ...

There are a few details left, but they are pretty straight forward so I'll leave them for you to do.

Our "signin" method on the Auth controller has yet to be implemented. For the most part, it's similar to the our "signup" flow. I would recommend validating the data that comes from the form, but this time you do not need to have a "password_confirmation". What you do have is a "remember_me" input field that's a boolean. You'd want to update the User model with that information and persist it in the database before redirecting the user to our dashboard.
We don't have anyway to "signout" yet. It would be nice if you could only "signout" after you've authenticated.

Easily Add TailwindCSS to Your AdonisJS Project

Warren Wong — Fri, 02 Apr 2021 02:18:34 +0000

If you haven't created a base AdonisJS project yet, check out my post on setting up VSCode for AdonisJS where I walk you through both creating a new AdonisJS project as well customizing the VSCode Prettier formatter to my liking.

Laravel Mix is a wrapper around Webpack that helps abstract away a lot of the confusing Webpack configurations and is especially useful when used with an MVC framework like Laravel and AdonisJS.

First, you'll need to install it through npm or yarn then create a webpack.mix.js file:

# 1a. npm
npm i -D laravel-mix

# 1b. yarn
yarn add -D laravel-mix

# 2.
touch webpack.mix.js

Before we go any further, let's decide where to put our front end assets. Looking at some guidance from the AdonisJS 4.1 docs, looks like a good place to put them would be in resources/assets.

So let's create a TypeScript file that will serve as our entry into the front end scripts as well as a CSS file to load TailwindCSS.

mkdir resources/assets
mkdir resources/assets/ts
touch resources/assets/ts/app.ts
mkdir resources/assets/css
touch resources/assets/css/app.css

Now let's install Tailwind and the associated dependencies:

# npm
npm i -D tailwindcss@latest postcss@latest autoprefixer@latest

# yarn
yarn add -D tailwindcss@latest postcss@latest autoprefixer@latest

Create the tailwind.config.js file:

npx tailwindcss init

While you CAN just touch tailwind.config.js, this command actually tests to see if you have dependencies like PostCSS. If something went wrong, you'll know at this stage.

Now let's set it up to remove unused styles. This step is critical if you want to deliver the smallest bundle size.

If this was just a quick project where you didn't need to customize your Tailwind configuration and didn't care about the bundle size, the easiest way to leverage TailwindCSS would be to just bring in Tailwind via CDN.

 {
  purge: [
    "./resources/views/**/*.edge",
    "./resources/assets/ts/**/*.ts",
  ],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Now open up the webpack.mix.js file we created earlier and configure the entry and output for our TypeScript and CSS files.

const mix = require("laravel-mix");

mix.setPublicPath("public");

mix
  .ts("resources/assets/ts/app.ts", "js/app.js")
  .postCss(
    "resources/assets/css/app.css",
    "css",
    [require("tailwindcss")]
  );

We need to set the public path to public because that's where the static assets for our AdonisJS project are located. Laravel Mix can handle TypeScript files as long as you install ts-loader as a dependency, so let's do that:

# npm 
npm i -D ts-loader

# yarn
yarn add -D ts-loader

You'll notice that I placed the transpiled JavaScript in the public/js directory and the resulting CSS file in public/css. We will need to know that when we edit our HTML file.

Now let's place our @tailwind directives in our empty app.css file as per a normal Tailwind setup:

@tailwind base;
@tailwind components;
@tailwind utilities;

Now let's run mix to build the front end assets:

npx mix

You will now see the new files in your public directory. Go ahead and place them in your Edge template:

  <link rel="stylesheet" href="css/app.css'">
  <script src="js/app.js'"></script>

Go ahead and inspect the app.css file to see that the @tailwind directives have been replaced with the Tailwind library.

Setting Up Visual Studio Code for AdonisJs Development

Warren Wong — Thu, 01 Apr 2021 10:32:39 +0000

After working with some of the more mature MVC frameworks like Laravel and Phoenix, I was excited to see AdonisJS hit 5.0 and fully support TypeScript.

It's fairly easy to start a new AdonisJS project:

# npm
npm init adonis-ts-app example-app

# yarn
yarn create adonis-ts-app example-app

Answer the questions for whichever build and setup you want. I selected web so AdonisJS brings in @adonisjs/view as a dependency. I also selected ESLint and Prettier since I want VSCode to automatically format my files for me.

Need to install the following packages:
  create-adonis-ts-app
Ok to proceed? (y)
    _       _             _         _
   / \   __| | ___  _ __ (_)___    | |___
  / _ \ / _` |/ _ \| '_ \| / __|_  | / __|
 / ___ \ (_| | (_) | | | | \__ \ |_| \__ \
/_/   \_\__,_|\___/|_| |_|_|___/\___/|___/


CUSTOMIZE PROJECT
❯ Select the project structure · web
❯ Enter the project name · example-app
❯ Setup eslint? (y/N) · true
❯ Setup prettier? (y/N) · true

RUNNING TASKS
❯ Scaffold project 80 ms
❯ Scaffold project 80 ms
❯ Install dependencies 42 s
❯ Configure installed packages 2.1 s

[ success ]  Project created successfully

╭─────────────────────────────────────────────────╮
│    Run following commands to get started        │
│─────────────────────────────────────────────────│
│                                                 │
│    ❯ cd example-app                             │
│    ❯ node ace serve --watch                     │
│                                                 │
╰─────────────────────────────────────────────────╯

If you look at the package.json file, you will see some useful scripts have already been generated for you.

{
  "scripts": {
    "build": "node ace build --production",
    "start": "node server.js",
    "dev": "node ace serve --watch",
    "lint": "eslint . --ext=.ts",
    "format": "prettier --write ."
  },
}

While you CAN run the linter and formatter through npm or yarn, I'd like VSCode to format files on save. Find Preferences>Settings on the dropdown menu then search for "formatOnSave". If you want this setting to apply to all your projects, click on the "User" tab, but I like to commit my .vscode/settings.json file to my git repository, so I'll select "Workspace" then click to edit the settings.json file. Update the file like so:

{
  "editor.formatOnSave": true,
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
}

This tells VSCode to use "esbenp.prettier-vscode" to format TypeScript files which make up all the app files for AdonisJS 5.0 projects.

Now let's look at the .prettierrc file.

These are the AdonisJS defaults that I guess @AmanVirk1 likes, but I'm more partial to semicolons so I'll be changing my file:

{
  "trailingComma": "es5",
  "semi": true, // updated from false
  "singleQuote": false, // updated from true
  "useTabs": false,
  "quoteProps": "consistent",
  "bracketSpacing": true,
  "arrowParens": "avoid", // updated from "always"
  "printWidth": 100
}

I like double-quotes and I'd like to avoid the parentheses on my arrow functions.

There are a couple VSCode extensions that you'll need for everything to work: dbaeumer.vscode-eslint and esbenp.prettier-vscode

Now open start/routes.ts and save the file. It should now automatically add in those awesome semicolons. ;)

Now let's go and update all the files in the project:

npm run format

One last thing. Let's remove .vscode from the .gitignore file so we can commit it into the repo.

Adding a Date Format Filter in Nuxt

Warren Wong — Tue, 29 Sep 2020 17:03:04 +0000

Since NuxtJS is just an opinionated VueJS with built in state management and routing, writing a filter for your template is just the same for Nuxt as it is for Vue, except for one catch. For now, let's start with a date formatter inside a component. Inside your component script tag, give the extends method your options object with a property of filters. Filter will be an object literal. The property names will be the name of the filter within the component. I don't really have any fancy formatting in mind, so let's just call this filter "formatDate". From a little bit of googling, I found the built in Intl.DateTimeFormat. This looks like it's exactly what we need. It seems to handle language specific formatting as well as time zones. I don't really need those yet, and I only write in English so I'm used to seeing the mm/dd/yyyy. For now, I think that's enough for me.

import Vue from "vue";
export default Vue.extend({
  filters: {
    formatDate: (date: Date) =>
      Intl.DateTimeFormat("us-EN").format(date),
  },
});

One snag is that I'm using Nuxt Content and I want to show the createdAt string that the module provides based on when the markdown file was created. createdAt returns a date in the form of a string, so I'll have to update the filter to handle that directly.

import Vue from "vue";
export default Vue.extend({
  filters: {
    formatDate: (dateStr: string) =>
      Intl.DateTimeFormat("us-EN").format(new Date(dateStr)),
  },
});

If we test that in the template, it seems to work just fine.

<template>
  <div>
    Date: {{ post.createdAt | formatDate }}
  <div>
</template>

Now, this filter seems pretty useful. I'd think we would need this in a lot of
pages and components so we should make this filter available to all the
templates.

In plain Vue, you can just register the filter with Vue like so:

Vue.filter("formatDate", (dateStr: string) =&gt;
  Intl.DateTimeFormat("us-EN").format(new Date(dateStr))
);

It's actually just the same in Nuxt, but we will be putting the filter in a
plugin that's registered in the nuxt.config.ts file.

In the /plugins directory, create a file called format-date.ts. We "plugins"
we put here are run before the root VueJS app gets instantiated.

import Vue from "vue";

Vue.filter("formatDate", (dateStr: string) =&gt;
  Intl.DateTimeFormat("us-EN").format(new Date(dateStr))
);

If we check our prior rendered page, the filter should still work after the page hot reloads.

Object Oriented Playing Cards in Python

Warren Wong — Thu, 13 Jun 2019 00:00:00 +0000

enum became a part of the Python standard library starting in version 3.4 and I thought that the classic OOP playing cards example would be a good demonstration of it.

In this example, I'm not going to worry about the actual playing card values like in Poker (twos are more valuable than threes, spades are more valuable than hearts, etc.) since there are many games where cards may not conform to those values.

I'll first create the set of four enums for the suite and the set of thirteen enums for the card's face value. I'll also use auto, since I'm not going to worry about the exact value of the enum, though I'll list them in Poker value order and auto will automatically give me those values anyway.

from enum import Enum, auto

class Suite(Enum):
    DIAMOND = auto()
    CLUB = auto()
    HEART = auto()
    SPADE = auto()

class Value(Enum):
    TWO = auto()
    THREE = auto()
    FOUR = auto()
    FIVE = auto()
    SIX = auto()
    SEVEN = auto()
    EIGHT = auto()
    NINE = auto()
    TEN = auto()
    JACK = auto()
    QUEEN = auto()
    KING = auto()
    ACE = auto()

Now I'll create the Card class with getters and setters so I can ensure the proper enums are passed when initializing each card.

class Card:
    def __init__ (self, suite: Suite, value: Value):
        self.suite = suite
        self.value = value

    @property
    def suite(self):
        return self._suite

    @property
    def value(self):
        return self._value

    @suite.setter
    def suite(self, suite: Suite):
        if suite not in Suite:
            raise Exception
        self._suite = suite

    @value.setter
    def value(self, value: Value):
        if value not in Value:
            raise Exception
        self._value = value

    def __repr__ (self):
        return f"<Card {self.value} of {self.suite}>"

If we try to initialize the Card with anything other than a valid Suite or Value, Python will raise an Exception.

Okay, now we can create a class for a deck of cards.

class Deck:
    def __init__ (self):
        self.cards = [Card(s, v) for s in Suite for v in Value]

    def __repr__ (self):
        output = [f"{c}\n" for c in self.cards]
        return "".join(output)

Now, let's give this a try and see if everything is alright.

>>> from card import Suite, Value, Card, Deck
>>> deck = Deck()
>>> len(deck.cards)
52
>>> deck
<Card Value.TWO of Suite.DIAMOND>
<Card Value.THREE of Suite.DIAMOND>
<Card Value.FOUR of Suite.DIAMOND>
<Card Value.FIVE of Suite.DIAMOND>
<Card Value.SIX of Suite.DIAMOND>
<Card Value.SEVEN of Suite.DIAMOND>
<Card Value.EIGHT of Suite.DIAMOND>
<Card Value.NINE of Suite.DIAMOND>
<Card Value.TEN of Suite.DIAMOND>
<Card Value.JACK of Suite.DIAMOND>
<Card Value.QUEEN of Suite.DIAMOND>
<Card Value.KING of Suite.DIAMOND>
<Card Value.ACE of Suite.DIAMOND>
<Card Value.TWO of Suite.CLUB>
<Card Value.THREE of Suite.CLUB>
<Card Value.FOUR of Suite.CLUB>
<Card Value.FIVE of Suite.CLUB>
<Card Value.SIX of Suite.CLUB>
<Card Value.SEVEN of Suite.CLUB>
<Card Value.EIGHT of Suite.CLUB>
<Card Value.NINE of Suite.CLUB>
<Card Value.TEN of Suite.CLUB>
<Card Value.JACK of Suite.CLUB>
<Card Value.QUEEN of Suite.CLUB>
<Card Value.KING of Suite.CLUB>
<Card Value.ACE of Suite.CLUB>
<Card Value.TWO of Suite.HEART>
<Card Value.THREE of Suite.HEART>
<Card Value.FOUR of Suite.HEART>
<Card Value.FIVE of Suite.HEART>
<Card Value.SIX of Suite.HEART>
<Card Value.SEVEN of Suite.HEART>
<Card Value.EIGHT of Suite.HEART>
<Card Value.NINE of Suite.HEART>
<Card Value.TEN of Suite.HEART>
<Card Value.JACK of Suite.HEART>
<Card Value.QUEEN of Suite.HEART>
<Card Value.KING of Suite.HEART>
<Card Value.ACE of Suite.HEART>
<Card Value.TWO of Suite.SPADE>
<Card Value.THREE of Suite.SPADE>
<Card Value.FOUR of Suite.SPADE>
<Card Value.FIVE of Suite.SPADE>
<Card Value.SIX of Suite.SPADE>
<Card Value.SEVEN of Suite.SPADE>
<Card Value.EIGHT of Suite.SPADE>
<Card Value.NINE of Suite.SPADE>
<Card Value.TEN of Suite.SPADE>
<Card Value.JACK of Suite.SPADE>
<Card Value.QUEEN of Suite.SPADE>
<Card Value.KING of Suite.SPADE>
<Card Value.ACE of Suite.SPADE>

Structure a Flask React Monorepo

Warren Wong — Sat, 08 Jun 2019 00:00:00 +0000

This is my project structure for a Flask server and React client residing in the same git repository. It's fairly similar to the many NodeJS, React monorepos out there where the server code will be in the server subdirectory and the client code will reside in the client subdirectory.

First, let's start by creating the project directory and intialize the git repository:

mkdir flask-react-monorepo
cd flask-react-monorepo
git init

Let's create a virtual environment for the repo with venv and place it in the venv directory inside the project. We will want to add this to our .gitignore file also. Once we have our virtual environment set up, we'll need to let our system know to use it.

python -m venv venv
echo venv/ > .gitignore
source venv/bin/activate

Let's install our dependencies, first for Python, then keep a list of the dependencies in a file called requirements.txt.

pip install Flask
pip freeze > requirements.txt

requirements.txt (your versions may vary)

Click==7.0
Flask==1.0.3
itsdangerous==1.1.0
Jinja2==2.10.1
MarkupSafe==1.1.1
Werkzeug==0.15.4

The canonical way to structure flask apps have a Python package named whatever the actual app is supposed to be within a subdirectory. Check out the Flask tutorial here for more details.

For now, let's call the Flask server server. It can easily be api or something else you prefer.

mkdir server

For our Flask setup to work, we will need to create a file named setup.py in the root of our project directory:

setup.py

from setuptools import setup

setup(
    name='server',
    packages=['server'],
    include_package_data=True,
    install_requires=['flask']
)

Now, let's just set up a simple Flask app in the server Python package by having an __init__.py file in our server directory.

server/ __init__.py

from flask import Flask

app = Flask( __name__ )

@app.route('/')
def index():
    return 'Hello, World!'

Now comes for the fun part of integrating our JavaScript client. I'll simply use create-react-app for this, but you can pretty much replace this with any front end framework or CLI tools you like.

From the project root:

create-react-app client

Now, we can go and type FLASK_APP=server flask run from the project root to run our development server and, from another terminal, run yarn start from the client directory to run the development client, but that's just 1 too many steps for me.

To streamline the development process, I'll also use yarn in the project root and install the concurrently package.

From the root directory:

yarn init
yarn add -D concurrently
echo node_modules/ >> .gitignore

Now, let's add some scripts to the package.json file yarn init generated. I want yarn client to run the client development server and yarn server to run the backend development server. I also want to call yarn start from the root to run both concurrently.

{
  "name": "flask-react-monorepo",
  "version": "1.0.0",
  "main": "index.js",
  "author": "Warren Wong <me@warrenwong.org>",
  "license": "MIT",
  "devDependencies": {
    "concurrently": "^4.1.0"
  },
  "scripts": {
    "start": "concurrently \"yarn client\" \"yarn server\"",
    "client": "cd client && yarn start",
    "server": "FLASK_APP=server flask run"
  }
}

If everything works out, your back end will be on port 5000 and your client will be on port 3000 by default.

Setting Up TypeScript for Node

Warren Wong — Sat, 01 Jun 2019 00:00:00 +0000

Today, I wanted to go over how to set up a TypeScript project for NodeJS from scratch.

It's something that I do fairly often and so it's nice to have this as a starter repo for some of my future NodeJS projects.

Let's first create a new directory for this project. I'll just call it ts-node-demo for now, but you can just rename it at a later date when you use it to start a new project.

mkdir ts-node-demo
cd ts-node-demo

Let's make this a git repository and use yarn for our package manager. It'll be a good idea not to commit any of our dependencies into our repo as well.

git init
yarn init
echo node_modules/ > .gitignore

Now I'll add the most basic dependencies for our TypeScript NodeJS project. Rather than doing an explicit build step and then running the plan JavaScript file that is a result of that build, I want to use the ts-node library that will take care of that for me. I'll, of course, also add TypeScript as well as the type definitions for NodeJS.

yarn add ts-node typescript @types/node

It'll be nice if I didn't have to restart the dev server everytime I save a file so let's add ts-node-dev. If you've ever worked with nodemon, this is pretty much the same, but for TypeScript.

yarn add -D ts-node-dev

package.json

{
  "name": "ts-node-demo",
  "version": "1.0.0",
  "main": "index.js",
  "author": "Warren Wong<me@warrenwong.org>",
  "license": "MIT",
  "dependencies": {
    "@types/node": "^12.0.4",
    "ts-node": "^8.2.0",
    "typescript": "^3.5.1"
  },
  "devDependencies": {
    "ts-node-dev": "^1.0.0-pre.39"
  }
}

I'll update the package.json to reflect the change to using TypeScript by changing index.js to index.ts. I should go ahead and create that file as well.

touch index.ts

Now let's add some scripts for starting the production app as well as starting the dev server. Since a service like Heroku would use yarn start or npm start to start the production server, I'll go ahead define "start" as "yarn ts-node index.ts". To start the dev server, I want to just type yarn dev, so I'll define "dev" as "yarn ts-node-dev index.ts".

package.json

{
  "name": "ts-node-demo",
  "version": "1.0.0",
  "main": "index.ts",
  "author": "Warren Wong <me@warrenwong.org>",
  "license": "MIT",
  "dependencies": {
    "ts-node": "^8.2.0",
    "typescript": "^3.5.1"
  },
  "devDependencies": {
    "@types/node": "^12.0.4",
    "ts-node-dev": "^1.0.0-pre.39"
  },
  "scripts": {
    "start": "yarn ts-node index.ts",
    "dev": "yarn ts-node-dev index.ts"
  }
}

Now to check if everything worked out, I'll need index.ts to actually do something.

index.ts

console.log("Hello, World!");

Okay, time to test this out.

yarn dev

Using ts-node version 8.2.0, typescript version 3.5.1
Hello, World!

yarn start

Hello, World!

What the heck are args and kwargs?

Warren Wong — Sun, 19 May 2019 00:00:00 +0000

So you're looking at someone's Python code and see something crazy, like *args and **kwargs. What the heck are those?

We will have to unpack it since there's a couple things that maybe causing confusion. First off, what does the * and ** do? Then, what do args and kwargs mean? And finally, what is it used for?

The * is a way of unpacking the list or tuple data structure and the ** is a way of unpacking a dict. args as you can guess, means arguments. Now kwargs maybe harder to guess, but you can probably deduce "kw" to mean "keyword". With that, you can guess that args represents the arguments passed to a function separated by a comma and kwargs are the keyword arguments.

The main reason for using args and kwargs are pretty simple if you're trying to create a higher-order function in Python. Rather than passing in a bunch of named arguments as well as keyword arguments, using args and kwargs allows for generalizing the the function signature so that you can accommodate almost any function.

Reference

Unpacking Argument Lists

Associate HTML as Jinja Files in VSCode

Warren Wong — Fri, 26 Apr 2019 00:00:00 +0000

Visual Studio Code can give you syntax highlighting for your Jinja templates even though Jinja files are usually named with a *.html extension in Flask projects.

I assume you already have the Python Extension for VSCode installed.

Open your Preferences > Settings from the dropdown menu or your settings.json file inside your current project's .vscode directory and add:

{
  "files.associations": {
    "*.html": "jinja-html"
  }
}

I wouldn't put this in the user settings.json file since that will globally associate all *.html files with jinja-html.