Forem: Carlo Miguel Dy

Firebase Cloud Functions Jest Setup with TypeScript & Mocking

Carlo Miguel Dy — Sun, 14 Nov 2021 14:22:30 +0000

Overview

As the backend requirements grows with 0% test coverage, the harder it is to maintain the project or even scale due to bugs coming out from anywhere. Debugging without tests also takes so much time to have to manually open the app, login using the credentials that you remember for a particular user role, and finally following the necessary steps to replicate the bug only to read off the error message or find out if it's working. It's a waste of time writing functionalities without tests, you didn't actually "save" time by not writing tests.

Introduction

We're only going to cover how to setup Jest with TypeScript and a basic unit test and fairly simple mocking to a class that we want to mock a response value of a certain method.

Setup Jest TypeScript

Setting up Jest on Cloud Functions is fairly simple and straight-forward. Just run the following command and you're ready to go!

npm i jest @types/jest ts-jest typescript -D

The following are the dependencies that our Cloud Functions directory in functions directory requires. We'll break it down below of what they are and what's their purpose.

Dependencies:

jest a testing framework maintained by Facebook, works well with frontend frameworks like Vue, React, Angular also with TypeScript. We'll be using Jest for writing up all of our unit tests, integration tests, and other types of tests that you know of.
@types/jest all the TypeScript typings are found here, we're getting the auto complete sugar that we developers love
ts-jest there are some utility functions that with help us mock a few functions or methods from a third party library
typescript our favorite tool

Once all the dependencies are installed, then all is cool! Next up is we create a file called jest.config.js at the root of our functions directory and we'll have the following lines of code in the newly created file.

module.exports = {
  "roots": [
    "<rootDir>/src"
  ],
  "testMatch": [
    "**/__tests__/**/*.+(ts|tsx|js)",
    "**/?(*.)+(spec|test).+(ts|tsx|js)"
  ],
  "transform": {
    "^.+\\.(ts|tsx)$": "ts-jest"
  },
}

Now we'll add a script in our package.json file on key scripts

// package.json
{
    "scripts": {
        // ... other scripts
        "test": "jest"
    }
}

Now by the following setup that we have, we will have all of our tests suites housed inside src directory. Here are the following examples on how the structure would look.

functions
    - src
        - todo
            - todo.service.ts
            - todo.spec.ts // or you can name it as "todo.test.ts"
        - todo-b
            - todo-b.service.ts
            - todo-b.spec.ts // or you can name it as "todo-b.test.ts"

And when we want to execute or run our tests cases, we'll use the following command

jest # or you can run with "npm run test" or "npm test"

You can read more for the full documentation from here

Writing our First Unit Test

Suppose that TodoService (relative path todo/todo.service.ts) is the class we want to test.

// todo.service.ts

export class TodoService {
    public giveMeANumber(number: number): number {
        return number;
    }
}

Then we will proceed to create a test/spec file in the same directory as the service so we can easily find its corresponding test file.

// todo.service.spec.ts

import { TodoService } from './todo.service.ts'

describe('TodoService', () => {
    let service: TodoService

    beforeEach(() => {
        service = new TodoService()
    })

    describe('giveMeANumber', () => {
        test('when value is true, then should return true', () => {
            expect(true).toBe(true)
        })

        it('should return 5, when given parameter is 5', () => {
            const number = service.giveMeANumber(5)

            expect(number).toBe(5)
        })
    })
})

Notice how we did not import describe, test, beforeEach, it, and expect functions because the setup that we have for Jest already handled it for us, the functions are available on all *.spec.ts or *.test.ts files. And lastly it's the @types/jest that will give us the convenience of auto-completes so we don't have to worry if we're passing down the correct arguments into those functions.

The describe function describes the test suite or it groups a set of test cases in it. It is very similar to group when we are writing tests in Flutter. And the test function is the actual test case.

And now to run our tests we will use the following command in the terminal. Suppose that you are in the root directory of the project, in this case it's ./functions

jest # `npm test` or `npm run test`

Note: It will take about under 10s to run the test, not sure why it's this slow.

Then that should display the test results in your terminal.

When you want to run specific tests, you can use jest -t 'when value is true, then should return true' make sure it matches that test case you want to run.

Writing our First Test with Mocking

And now we are going to make mocks to any third party libraries that we depend on so we don't have to make the test await for any HTTP calls.

Say TodoService will have a dependency for AwesomeTodoAPI where we want to make a call only to retrieve outstanding todos. And we just want to assert the array length of the response data just to make an assertion example as simple as possible. The only thing we want to learn now is how we can create mocks in Jest with TypeScript.

Now let's have the same service class but is dependent to a library AwesomeTodoAPI where this dependency will handle the HTTP calls internally, so we're only calling methods from it that will give us the resources we require.

// todo.service.ts

import AwesomeTodoAPI from '@awesome/AwesomeTodoAPI'

type AwesomeTodo = {
    title: string
    description: string
}

export class TodoService {
    private awesomeTodoApi: AwesomeTodoAPI

    constructor() {
        this.awesomeTodoApi = new AwesomeTodoAPI()
    }

    public async fetchOutstandingTodos(): Promise<AwesomeTodo[]> {
        const response = await this.awesomeTodoApi.fetchOutstandingTodos()
        return response.data
    }

    public giveMeANumber(number: number): number {
        return number;
    }
}

The method fetchOutstandingTodos inside our TodoService is dependent on the returned response from AwesomeTodoAPI method fetchOutstandingTodos. We can then proceed to creating a mock of the returned response for that. Without mocking, it will still make the actual call for fetchOutstandingTodos but that'll take some time before the data gets returned and will result into making our tests running slow, and that's not what we want in this case since we'll only want to unit test our code and not make an integration test.

On the same spec/test file that we have,

// todo.service.spec.ts

import { mocked } from "ts-jest/utils";
import { TodoService } from './todo.service.ts'
import { AwesomeTodoAPI } from '@awesome/AwesomeTodoAPI'

// Let Jest automatically create all the mocks for us
jest.mock('@awesome/AwesomeTodoAPI')

describe('TodoService', () => {
    let service: TodoService
    const mockedAwesomeTodoApi = mocked(AwesomeTodoAPI, true)

    beforeEach(() => {
        service = new TodoService()

        // Clear out all the mocks that we 
        // created before each test case
        mockedAwesomeTodoApi.mockClear()
    })

    describe('fetchOutstandingTodos', () => {
        test('when called, should return all the outstanding todos', async () => {
            // Arrange: Mock the returned response value
            AwesomeTodoAPI.prototype.fetchOutstandingTodos = jest.fn()
                .mockImplementationOnce(() => {
                    return {
                        data: [
                            { title: 'Todo A', description: 'lorem', },
                            { title: 'Todo B', description: 'lorem', },
                        ] as AwesomeTodo[]
                    } as AwesomeTodoAPIResponse
                })

            // Action
            const todos = await service.fetchOutstandingTodos()

            // Assert
            expect(todos.length > 1).toBeTruthy()
        })

        test('when there are no outstanding todos, should return empty array', async () => {
            // Arrange: Mock the returned response value
            AwesomeTodoAPI.prototype.fetchOutstandingTodos = jest.fn()
                .mockImplementationOnce(() => {
                    return {
                        data: [] as AwesomeTodo[]
                    } as AwesomeTodoAPIResponse
                })

            // Action
            const todos = await service.fetchOutstandingTodos()

            // Assert
            expect(todos.length === 0).toBeTruthy()
        })
    })
})

Now to break it down for you on what's happening:

We imported AwesomeTodoAPI from '@awesome/AwesomeTodoAPI' and automatically created a mock for all of its method by calling jest.mock(importPath, factoryCallback) (You can learn more about the factoryCallback I am referring to from the official Jest docs if you wish to, basically you just have to match all method names and its return values, and have the callback return an object. It's obviously a boilerplate code but maybe there can be a potential use case for manually setting up mocks)
Next is we create a variable called mockedAwesomeTodoApi where this is the actual mock and thanks to the utility function mocked from ts-jest where we pass down in the first argument of the object we want to mock and its second argument is if we want to mock it deep so we set true
Inside beforEach is we setup our service TodoService and clear out all the mocks that was created previously from each test case, so before each test case will be a fresh mock by calling mockClear from the mocked object
Now inside our test suite for method fetchOutstandingTodos on the "Arrange" section is we setup the return response value of the AwesomeTodoAPI for its method fetchOutstandingTodos since we don't want to make an actual call to the API. The way we mock the returned response is by accessing the class prototype itself, and access fetchOutstandingTodos and assign a new value to it by what is returned in the callback function for mockImplementationOnce
Then we make the actual call from our TodoService that calls fetchOutstandingTodos from AweomseTodoAPI and pass down the returned value to the todos variable
Finally we assert if todos contains some data or if it's empty.

Wrapping Up

We learned how to setup Jest with TypeScript in just a few minutes. Now we can get our tests up and running in no time!

Thanks for taking the time to read. Good day!

Unit Testing a Solidity Smart Contract using Chai & Mocha with TypeScript

Carlo Miguel Dy — Thu, 21 Oct 2021 01:32:17 +0000

Overview

I've recently been playing around writing some smart contracts for fun with Solidity and the fastest way to validate the logic you wrote works as what you expect it to do is by unit testing. It was also a fun experiencing testing smart contracts with Chai and Mocha together with TypeScript. It made things quick and easy for me. And cheers to Hardhat for making things much more easier and convenient that it automatically generates all the TypeScript typings of a smart contract via Typechain. In this article we're only going to cover how we set it up using Hardhat and how we can make those assertions.

But why should we unit test our smart contracts? Can't we just deploy it manually using the Hardhat deploy script and from the UI we can point-click and test it from there? Yes, we can but eventually it's going to take us so much time, you can count off how many steps it took to validate that the smart contract that we wrote has been working as what we expect. With unit testing, we can directly make calls to those methods and make the assertions or even console logging if you so desire to in a single test file.

However, if you're still new to Ethereum Development or Blockchain Development, then be sure to check out Nader Dabit's article for a complete guide to Full Stack Ethereum Development 🔥

With all that being said let's get right on to it. 🚢

The Stack

Outlining the stack that we are using for this tutorial:

Installation

As mentioned above we are going to use Hardhat for this. Just in case you don't know what Hardhat is, it provides a development environment for Ethereum based projects. It's very intuitive I like it and the documentation is also great. You can visit the docs from here.

Let's get started.

Setup a new directory called smart-contract-chai-testing (Or whichever you prefer to name it)



# you can omit the $ sign
$ mkdir smart-contract-chai-testing

Then navigate into the new directory created



$ cd smart-contract-chai-testing

We'll initialize a local Git repository to make things easier for us to visually see in the source control on what things were recently added or modified (I prefer it this way but you can omit this step)



$ git init

Next is we'll initialize a Hardhat project with the following command (Assuming that you have Node.js installed already in your machine)



$ npx hardhat init

You should then see the following output in your terminal

And proceed to selecting "Create an advanced sample project that uses TypeScript", it will just scaffold everything for us. When that gets selected, just say yes (Y) to all questions the CLI asks.

Now that's all setup we can open the code in our favorite IDE, the almighty Visual Studio Code.



$ code .

And finally stage all the changes and commit with "Init" message



$ git add . && git commit -m "Init"

Running a Test

As you notice like any other Hardhat initial projects, we got a Greeter smart contract. In this scaffolding we also have that and got a test case on TypeScript. So to trigger a test execute the following command in your terminal. A test on test/index.ts will get executed.



$ npx hardhat test

When that is called it is going to compile your smart contract as quickly as possible and with Hardhat's Typechain it's going to auto-generate all the TypeScript typings for that smart contract Greeter. That's very convenient isn't it? When writing smart contracts with Hardhat's Typechain plugin or library, there's literally zero boilerplate.

You can see it for yourself and inspect the directory generated called typechain along with the artifcats directory that was generated too as the smart contract was compiled.

Updating the Greeter smart contract

Ok so we'll modify our Greeter contract to have some slightly interesting test cases. In this smart contract it should do the following:

Should have a function sum that returns the sum of two numbers provided
A user can store their lucky number, they are only allowed to store a lucky number when they don't have a lucky number stored yet. Otherwise the execution will revert.
A user can update their lucky number, only if they remember correctly their previous lucky number. Otherwise the execution will revert.

The requirements are a bit confusing aren't they? But that's exactly why we should be writing tests so we exactly know its behavior on-chain and we can fix up bugs during development before it gets finally deployed to Mainnet.

You can update your Greeter smart contract and we'll then create test cases for it.



//SPDX-License-Identifier: Unlicense
pragma solidity ^0.8.4;

import "hardhat/console.sol";

contract Greeter {
    mapping(address => uint256) public ownerToLuckyNumber;

    constructor() {
        console.log("Deployed Greeter by '%s'", msg.sender);
    }

    function sum(uint256 a, uint256 b) public pure returns (uint256) {
        return a + b;
    }

    function getMyLuckyNumber() external view returns (uint256) {
        return ownerToLuckyNumber[msg.sender];
    }

    modifier luckyNumberGuard() {
        /// @dev if it's not 0 then owner already has a lucky number
        require(
            ownerToLuckyNumber[msg.sender] == 0,
            "You already have a lucky number."
        );
        _;
    }

    modifier luckyNumberNotZero(uint256 _luckyNumber) {
        require(_luckyNumber != 0, "Lucky number should not be 0.");
        _;
    }

    function saveLuckyNumber(uint256 _luckyNumber)
        external
        luckyNumberGuard
        luckyNumberNotZero(_luckyNumber)
    {
        ownerToLuckyNumber[msg.sender] = _luckyNumber;
    }

    modifier shouldMatchPreviousLuckyNumber(uint256 _luckyNumber) {
        require(
            ownerToLuckyNumber[msg.sender] == _luckyNumber,
            "Not your previous lucky number."
        );
        _;
    }

    function updateLuckyNumber(uint256 _luckyNumber, uint256 _newLuckyNumber)
        external
        shouldMatchPreviousLuckyNumber(_luckyNumber)
    {
        ownerToLuckyNumber[msg.sender] = _newLuckyNumber;
    }
}

I've written few functions and few modifiers just to make things a bit interesting to test.

Writing our tests

Now we got our smart contract up to date to the requirements, the fun starts and we'll start testing it. Also I like to group my tests by function names on those function I am going to test it, it makes things easier to navigate in this test suite when things get bigger. Not only that but it helps me navigate easily when after a few months I have to look back at it again.

So basically I have the following structure:



describe("Greeting", () => {
  describe("functionName", () => {
        it("should return when given", async () => {
            // ...
    })
  })
})

The first describe is the smart contract name and each child describes are all the functions that are in that smart contract. But you can structure your tests in any way shape or form that you think it's much easier to go with.

Writing a test for function sum

Here's a test case for testing the sum function



import { expect } from "chai";
import { ethers } from "hardhat";
import { Greeter } from "../typechain";

describe("Greeter", function () {
  let contract: Greeter;

  beforeEach(async () => {
    const Greeter = await ethers.getContractFactory("Greeter");
    contract = await Greeter.deploy();
  });

  describe("sum", () => {
    it("should return 5 when given parameters are 2 and 3", async function () {
      await contract.deployed();

      const sum = await contract.sum(2, 3);

      expect(sum).to.be.not.undefined;
      expect(sum).to.be.not.null;
      expect(sum).to.be.not.NaN;
      expect(sum).to.equal(5);
    });
  });
});

For a quick breakdown, I created a local variable and used let to reassign it but have a type of Greeter which was generated by Typechain as the smart contract was compiled. And on the beforeEach for every test case it's going to execute that and set the value for the contract variable. So basically in all test cases we can just directly grab it off from there and not having to copy-paste the contract in each single test cases.

Now run the tests by the following command



$ npx hardhat test

You might want to make the script a bit shorter if you're using yarn or npm so open up your package.json file and add a script for it.



// package.json
{
    // ...  

    "scripts": {
      "test": "hardhat test"
    },

    // ...
}

And now we can run the tests by yarn test or npm test then we get the following result

Writing a test for getMyLuckyNumber function

Before we can assert getMyLuckyNumber we'll first have to save our lucky number into the smart contract to set the state in ownerToLuckyNumber and grab the value from there. For a short breakdown on what's happening on the test below. We have the contract deployed and we called saveLuckyNumber and pass down a value of 5 and once that's done we call getMyLuckyNumber and store it to a local variable myLuckyNumber we then proceed to assert and expect it to be not undefined and to be not null and finally since uint256 is considered a BigNumberish type we just then convert it to a simple JavaScript friendly number by calling toNumber on object type BigNumberish which is our myLuckyNumber local variable. Then just expect it to equal to 5 because we previously called saveLuckyNumber with value of 5.



import { expect } from "chai";
import { ethers } from "hardhat";
import { Greeter } from "../typechain";

describe("Greeter", function () {
  let contract: Greeter;

  beforeEach(async () => {
    const Greeter = await ethers.getContractFactory("Greeter");
    contract = await Greeter.deploy();
  });

  // ...

  describe("getMyLuckyNumber", () => {
    it("should return 5 when given 5", async () => {
      await contract.deployed();

      await contract.saveLuckyNumber(5);
      const myLuckyNumber = await contract.getMyLuckyNumber();

      expect(myLuckyNumber).to.be.not.undefined;
      expect(myLuckyNumber).to.be.not.null;
      expect(myLuckyNumber.toNumber()).to.equal(5);
    });
  });

  // ...
});

Now run that test by yarn test or npm test then we get the results

Writing tests for saveLuckyNumber function

Now here we can test out and expect reverts when a condition in the modifier does not satisfy.



import { expect } from "chai";
import { ethers } from "hardhat";
import { Greeter } from "../typechain";

describe("Greeter", function () {
  let contract: Greeter;

  beforeEach(async () => {
    const Greeter = await ethers.getContractFactory("Greeter");
    contract = await Greeter.deploy();
  });

  // ...

  describe("saveLuckyNumber", () => {
    it("should revert with message 'Lucky number should not be 0.', when given 0", async () => {
      await contract.deployed();

      await expect(contract.saveLuckyNumber(0)).to.be.revertedWith(
        "Lucky number should not be 0."
      );
    });

    it("should revert with message 'You already have a lucky number.', when owner already have saved a lucky number", async () => {
      await contract.deployed();

      await contract.saveLuckyNumber(6);

      await expect(contract.saveLuckyNumber(7)).to.be.revertedWith(
        "You already have a lucky number."
      );
    });

    it("should retrieve 66 when recently given lucky number is 66", async () => {
      await contract.deployed();

      await contract.saveLuckyNumber(66);
      const storedLuckyNumber = await contract.getMyLuckyNumber();

      expect(storedLuckyNumber).to.be.not.undefined;
      expect(storedLuckyNumber).to.be.not.null;
      expect(storedLuckyNumber).to.be.not.equal(0);
      expect(storedLuckyNumber).to.be.equal(66);
    });
  });

  // ...
});

For the first 2 tests, we intently make it fail by going against the modifiers that we defined. The modifiers are there to protect anything from unexpected behaviors, thus reverts it when it fails to satisfy the modifier.

For a breakdown of each test cases on saveLuckyNumber:

On the first test case, we pass down a value of 0 into saveLuckyNumber and on the smart contract on saveLuckyNumber we have a modifier attached to the function prototype. It expects a lucky number value anything other than 0. So when it's 0 it will always fail and will revert. Thus we have our expect assertion that the call will be reverted with the following message "Lucky number should not be 0.".
On the second test case, on the saveLuckyNumber function again we have a modifier defined that they will never be able to set a new lucky number from calling saveLuckyNumber because it's going to check into the mapping ownerToLuckyNumber to see if they have already a lucky number stored. If they do we'll never allow it to update the state in ownerToLuckyNumber of their address. Thus reverting with message "You already have a lucky number."
On the third test case, we just simply call and pass down a value of 66 to saveLuckyNumber and eventually just call getMyLuckyNumber and expect it to return 66

Now we'll run the tests again by yarn test or npm test and we have the following result

Writing tests for updateLuckyNumber

Finally for the last function that we will be testing. This function allows the User to update their existing lucky number on-chain only if so they remember their previous lucky number. If they don't remember then they can just check for it by calling getMyLuckyNumber



import { expect } from "chai";
import { ethers } from "hardhat";
import { Greeter } from "../typechain";

describe("Greeter", function () {
  let contract: Greeter;

  beforeEach(async () => {
    const Greeter = await ethers.getContractFactory("Greeter");
    contract = await Greeter.deploy();
  });

  // ...

  describe("updateLuckyNumber", () => {
    it("should revert with message '', when the given lucky number does not match with their existing lucky number", async () => {
      await contract.deployed();
      await contract.saveLuckyNumber(6);

      await expect(contract.updateLuckyNumber(8, 99)).to.be.revertedWith(
        "Not your previous lucky number."
      );
    });

    it("should update their lucky number, when given the exact existing lucky number stored", async () => {
      await contract.deployed();
      await contract.saveLuckyNumber(2);

      await contract.updateLuckyNumber(2, 22);
      const newLuckyNumber = await contract.getMyLuckyNumber();

      expect(newLuckyNumber).to.be.not.undefined;
      expect(newLuckyNumber).to.be.not.null;
      expect(newLuckyNumber.toNumber()).to.be.equal(22);
    });
  });
});

To break it down for you:

On the first test, we intently make the test fail. Say for a given scenario the User forgets their previous lucky number saved on-chain. So it shouldn't allow them to update their lucky number. So in the test we'll make them save lucky number of 6 and then some time around in the future they want to update it. So we call updateLuckyNumber where we pass value of 8 as the first function argument which is their "previous" lucky number because they believe so it was 8 and 99 as the second function argument which is the new lucky number they want to replace. So the smart contract will most likely prevent updating the state or their lucky number stored on-chain. Now we can safely assert that it was reverted with the message "Not your previous lucky number." (For now it's that, error message not too detailed but we're not concerned about good design in the scope of this tutorial)
On the second test, say User actually remembered their previous lucky number and they want to update it to a new lucky number. Then we assert the new lucky number which has a value of 22

Finally we'll run the tests one more time

And every thing passed! That gave us the assurance that our smart contract works as what we expect it to do. So that's a wrap!

Conclusion

We've covered creating a new project and a setup for Hardhat using the template that they provided which was extremely cool where we don't have to worry as much setting up those configurations ourselves. We've also learned how to make assertions in Chai and to expect certain values and expect a reversion with a revert message. And finally we notice how Typechain is working so well, it does most of the work for us by generating those types automatically every time we compile the smart contract, that was very convenient!

That's it for me, I hope you enjoy reading and hope that you learned something. Thanks for reading up until this point, have a good day and cheers!

If you haven't already joined a DAO, join your first DAO by going here @developer_dao go and mint your DAO NFT, get a pixel avatar and vibe into the Discord channel. See you there!

If you might have any questions or suggestions feel free to drop comments below I'd be happy!

Full source code available in the repository

Generating Fake Data in Flutter using the Factory Pattern for Unit Testing

Carlo Miguel Dy — Sat, 17 Jul 2021 13:56:02 +0000

Introduction

In this article we will learn how we can seamlessly generate fake data in Flutter that we can use with-in our test suites, or just for some placeholder data in our app when the backend is not completely setup yet or any other scenario that we just need a fake data in general. You will also learn how to create a Flutter package and use that package with-in your application, it can be used both in lib and test folder. And lastly you will learn how to setup a basic monorepo for your future projects, however I am not going to tackle about monorepos in this post on what are its pros and cons.

However, if you don't really need the monorepo setup, just skip over to the actual implementation of the Factory Pattern.

Packages

We will only require the following packages for us to seamlessly generate fake data.

faker: Will handle generating of random data of any data type.
uuid: Will generate a random uuid for us.
build_runner: Responsible for auto-generating us some boilerplate code.
freezed: Is where we create our data models.

Setup

To follow along, we'll start to setup a monorepo, first create your terminal and navigate into that directory on where you put up all your projects. I prefer to have mine under /dev/personal-projects so I'll cd into it.

Next up is create a directory and call it "flutter-fake-data-factory-pattern" via mkdir terminal command.

mkdir flutter-fake-data-factory-pattern

Then next is to initialize Git in this directory so we can start up to track changes. Or maybe upload this into your repository or not. Whichever you prefer.

cd flutter-fake-data-factory-pattern && git init

Create a new directory called packages and create a Flutter package inside that directory and call it app_core

mkdir packages

cd packages

flutter create --template=package app_core

Once that is done you can proceed with installing the dependencies mentioned above.

Have the following in your dependencies pubspec.yaml file

# Add this so our local package will not be published to pub.dev
publish_to: "none"

dependencies:
    freezed_annotation: ^0.14.2
    json_annotation: ^4.0.1
    faker: ^2.0.0
    uuid: ^3.0.4

dev_dependencies:
    build_runner: ^2.0.5
    freezed: ^0.14.2
    json_serializable: ^4.1.3

Install the dependencies afterwards.

cd app_core && flutter pub get

Next is to create a Flutter project is where our Flutter app lives. Now go up 2 directories via

cd ../..

Then create another directory and call it "apps", it is where we will house our Flutter apps.

mkdir apps

flutter create client_app

Then finally, just import the local package in "client_app" pubspec.yaml

app_core:
    path: ../../packages/app_core

Now that it is all setup and done we can proceed with the implementation of the Factory Pattern.

Keep in mind that since we have this kind of setup, all of our data models will be coming from the local package that we created app_core

Creating the ModelFactory abstract

We'll want to create an abstract class for our factory classes so that they will be aligned with the actual implementation, then we'll just have a generic type argument to pass down to differ its results when other classes implements the abstract.

import 'package:faker/faker.dart';
import 'package:uuid/uuid.dart';

abstract class ModelFactory<T> {
  Faker get faker => Faker();

  /// Creates a fake uuid.
  String createFakeUuid() {
    return Uuid().v4();
  }

    /// Generate a single fake model.
  T generateFake();

  /// Generate fake list based on provided length.
  List<T> generateFakeList({required int length});
}

We are only keeping it simple, we just want a single item and a List of items of a particular data model.

The getter faker is the Faker instance that got instantiated, it is where we grab all random data of any type.
Next is the createFakeUuid method which is responsible for generating us a fake uuid out of the fly. Typically uuids are used when you have a data provider like Firestore or NoSQL databases like MongoDB, or a relational database that has a primary key type of uuid. But you can switch this up any however you want it to be.
The generateFake is responsible for creating a single data model that requires implementation details; We'll have the implementation details for this in the factory class that extends this abstract class.
Lastly, the generateFakeList will return a list, implementation details are not concerned here as well and it is being handled in the factory class the implements this abstract. It will just simply return a list of what is returned from generateFake method.

Defining our data models

We'll just have it simple, we'll want two for now a User and a Tweet data model.

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user.g.dart';
part 'user.freezed.dart';

@freezed
class User with _$User {
  factory User({
    required String id,
    required String name,
    required String email,
    int? age,
    @Default(false) bool suspended,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

import 'package:freezed_annotation/freezed_annotation.dart';

part 'tweet.g.dart';
part 'tweet.freezed.dart';

@freezed
class Tweet with _$Tweet {
  factory Tweet({
    required String id,
    required String content,
    @Default([]) List<String> replies,
    @Default(0) int likes,
    @Default(0) int retweets,
  }) = _Tweet;

  factory Tweet.fromJson(Map<String, dynamic> json) => _$TweetFromJson(json);
}

Don't forget to run build_runner to let it generated the boilerplate code for us. Run it via this terminal command (You have to be in app_core directory otherwise this won't run):

flutter pub run build_runner build --delete-conflicting-outputs

If you want to learn more about data modeling with freezed package, read more about it from this tutorial that I wrote.

Creating a factory class

Now to implement the abstract class ModelFactory

import 'package:app_core/app_core.dart';

class UserFactory extends ModelFactory<User> {
  @override
  User generateFake() {
    return User(
      id: createFakeUuid(),
      email: faker.internet.email(),
      name: '${faker.person.firstName()} ${faker.person.lastName()}'.trim(),
      age: faker.randomGenerator.integer(25),
      suspended: faker.randomGenerator.boolean(),
    );
  }

  @override
  List<User> generateFakeList({required int length}) {
    return List.generate(length, (index) => generateFake());
  }
}

import 'package:app_core/app_core.dart';

class TweetFactory extends ModelFactory<Tweet> {
  @override
  Tweet generateFake() {
    return Tweet(
      id: createFakeUuid(),
      content: faker.lorem.words(99).join(' '),
      likes: faker.randomGenerator.integer(5000),
      retweets: faker.randomGenerator.integer(2500),
      replies: List.generate(
        faker.randomGenerator.integer(105),
        (index) => faker.lorem.words(120).join(' '),
      ),
    );
  }

  @override
  List<Tweet> generateFakeList({required int length}) {
    return List.generate(length, (index) => generateFake());
  }
}

Sample usage for generating fake data from the factory class

It's so easy and straight forward just like what you are thinking right now on how we can use these factory classes to generate us some fake data.

/// A new instance of [UserFactory]
final userFactory = UserFactory();

/// Generates a [User] data model
final fakeUser = userFactory.generateFake();

/// Will generate a [List] of 10 [User] data model
final fakeUsers = userFactory.generateFakeList(10);

We can just basically import it anywhere and we don't have to manually set up the values for each property a User data model has.

Conclusion

We learned how to use Faker package and applied abstraction to avoid writing up the same code again and again for other data models to generate fake data. This would come quite so handy when we write a lot of unit tests with mocking as we don't have to create a data model instance and define each properties for each test case. And lastly we can also make use of this in the UI for placeholder data when the API is not yet ready to integrate with the frontend app.

Full source code can be found from the repository

https://github.com/carlomigueldy/flutter-fake-data-factory-pattern

Laravel Inversion of Control Implementation using Contextual Binding

Carlo Miguel Dy — Sat, 19 Jun 2021 12:13:09 +0000

Introduction

In this post, we will tackle about "Inversion of Control" principle. We will learn when to use it and how we can use it with Laravel using Contextual Binding in the Service Container. Although this topic assumes that you have the basic knowledge with Laravel and a general OOP concepts.

At the time of writing this, the current version for Laravel is on version 8.

What is Inversion of Control?

If you know what is Dependency Injection then it's basically just a reverse of it. For Dependency Injection the code typically depends directly on the class. With Inversion of Control (IoC) we invert it, the code does not depend on the class directly but only to the interface and we bind it in the service container. So when we Inject dependency to a certain class or Controller we call the Interface and not the class.

When to use Inversion of Control?

One must be aware and has to fully understand the scenario or what problem or certain feature to be implemented. There are a lot of problems and are a lot of ways to address it. But to choose the proper method of addressing the problem is a good way to approach it. Things does not have to be complex and should just be simple as possible.

Other than that, say for a given scenario, your client wants to support multiple payment providers for the project that you are building. At your first glance you might think that you'll have to create a lot of classes for it and have different implementation details on each one of them, but the problem arises that you might have to inject a lot these in your Controllers or that you might have to put up some conditional logics just to use the correct payment provider.

That can work but it may not the ideal implementation. Then that's the time we will make use of abstraction using Inversion of Control, we can then only inject a single dependency to a Controller or whatever class it requires and that leaves us lesser code to write. It keeps it simple, and that also means it'll be easier to maintain it in the long term.

Creating a PaymentInterface

Just for a quick, simple, and straight-forward example let's have a PaymentInterface that requires 1 method to implement whichever a class implements this interface or abstract.

So let's just create a directory under app directory of a fresh Laravel project, and call this directory as Interfaces and have a file created named as PaymentInterface.php and for its content, we have this



<?php

namespace App\Interfaces;

interface PaymentInterface
{
  /**
   * @param float $amount 
   * @return mixed 
   */
  public function pay(float $amount): string;
}

We only require classes to implement pay method that takes an argument $amount type hinted with float and it returns a string

Creating payment services that implements PaymentInterface

Let's say the client wants to have at least 3 payment providers, let's just call it whatever we want in this case.

Paypal
SquarePay
Stripe

We have at least 3 payment providers but with different implementation details because we might have to setup a few configuration for each of these third party APIs. Typically we want these configuration setup private and should not be exposed publicly, we only expose what is defined in the PaymentInterface

So let's define these services, we'll start off with Paypal



<?php

namespace App\Services;

use App\Interfaces\PaymentInterface;

class PaypalService implements PaymentInterface
{
    public function pay(float $amount): string
    {
        return "From PaypalService $amount";
    }
}

The PaypalService implements the PaymentInterface and the pay method as well, and as defined from the abstract class or interface that pay should return a string then we'll return it with a type of string so we basically just know right away what we should be returning.

For the SquarePayService



<?php

namespace App\Services;

use App\Interfaces\PaymentInterface;

class SquarePayService implements PaymentInterface
{
    public function pay(float $amount): string
    {
        return "From SquarePayService $amount";
    }
}

For the StripeService



<?php

namespace App\Services;

use App\Interfaces\PaymentInterface;

class StripeService implements PaymentInterface
{
    public function pay(float $amount): string
    {
        return "From StripeService $amount";
    }
}

Now we have those defined and implemented the PaymentInterface we can move on to having to dynamically bind the interface with the corresponding class or payment provider.

Exposing the payment service providers to REST API

Now let's go over and create the controllers for each of these payment service providers that we defined. If you are coding along then open up your terminal and let's create these controllers using the artisan commands.



# Will create a directory called "PaymentProvider" and have 
# the controller named as defined "PaypalController" for example

# Paypal
php artisan make:controller PaymentProvider/PaypalController

# Stripe
php artisan make:controller PaymentProvider/StripeController

# SquarePay
php artisan make:controller PaymentProvider/SquarePayController

Then we'll go over each of these controllers and we will inject PaymentInterface into the constructor and pass it down into a private field.

PaypalController



<?php

namespace App\Http\Controllers\PaymentProvider;

use App\Http\Controllers\Controller;
use App\Contracts\PaymentInterface;
use Illuminate\Http\Request;

class PaypalController extends Controller
{
    private $paymentService;

    public function __construct(PaymentInterface $paymentService)
    {
        $this->paymentService = $paymentService;
    }

    public function index()
    {
        return response()->json([
            'data' => $this->paymentService->pay(250.0),
        ]);
    }
}

StripeController



<?php

namespace App\Http\Controllers\PaymentProvider;

use App\Http\Controllers\Controller;
use App\Contracts\PaymentInterface;
use Illuminate\Http\Request;

class StripeController extends Controller
{
    private $paymentService;

    public function __construct(PaymentInterface $paymentService)
    {
        $this->paymentService = $paymentService;
    }

    public function index()
    {
        return response()->json([
            'data' => $this->paymentService->pay(10.0),
        ]);
    }
}

SquarePayController



<?php

namespace App\Http\Controllers\PaymentProvider;

use App\Http\Controllers\Controller;
use App\Contracts\PaymentInterface;
use Illuminate\Http\Request;

class SquarePayController extends Controller
{
    private $paymentService;

    public function __construct(PaymentInterface $paymentService)
    {
        $this->paymentService = $paymentService;
    }

    public function index()
    {
        return response()->json([
            'data' => $this->paymentService->pay(5.0),
        ]);
    }
}

Once that's done, we can then expose these controllers as an endpoint to the REST API.

We define it in api.php



<?php

use App\Http\Controllers\PaymentProvider\PaypalController;
use App\Http\Controllers\PaymentProvider\SquarePayController;
use App\Http\Controllers\PaymentProvider\StripeController;
use Illuminate\Support\Facades\Route;

Route::get('pay-with-paypal', [PaypalController::class, 'index']);
Route::get('pay-with-stripe', [StripeController::class, 'index']);
Route::get('pay-with-squarepay', [SquarePayController::class, 'index']);

I just defined it with GET request HTTP method just for simplicity of the tutorial. But for actual payment implementations, prefer to use POST instead that it contains a payload data of payment information containing the amount, the account ID and any other sensitive information.

So there we defined it, you might be tempted to test it out with your HTTP client to see if it works. But actually it won't work yet as we didn't define it to act that way. So let's proceed to using Contextual Binding implementation.

Contextual Binding

We will be defining these bindings in the AppServiceProvider or you can create a different service provider that is relevant to its implementation, it can be PaymentServiceProvider (or any other name as you prefer) and have it registered in AppServiceProvider. But just for the sake of simplicity for the tutorial I will just bind the interface and their corresponding services directly into the AppServiceProvider.



<?php

namespace App\Providers;

use App\Http\Controllers\PaymentProvider\PaypalController;
use App\Http\Controllers\PaymentProvider\SquarePayController;
use App\Http\Controllers\PaymentProvider\StripeController;
use App\Interfaces\PaymentInterface;
use App\Services\PaypalService;
use App\Services\SquarePayService;
use App\Services\StripeService;
use Illuminate\Http\Request;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        $this->app->when(PaypalController::class)
            ->needs(PaymentInterface::class)
            ->give(PaypalService::class);

        $this->app->when(StripeController::class)
            ->needs(PaymentInterface::class)
            ->give(StripeService::class);

        $this->app->when(SquarePayController::class)
            ->needs(PaymentInterface::class)
            ->give(SquarePayService::class);
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        //
    }
}

On the register method of the AppServiceProvider is where we define the Contextual Binding, as you can see it checks on the Controller using the when method then the needs is referring to the dependency of that particular controller, and the last method chaining is give which is what we want to bind it to, these are the service classes that we defined PaypalService, StripeService, and SquarePayService.

In other words, if the PaypalController injects the PaymentInterface the service container would know that its corresponding binding will result to PaypalService and the same goes for StripeController and SquarePayController.

Now that we defined that in the service container, we can proceed to testing it out manually using our HTTP or just the browser to see if it worked.

Manually Testing in browser

It's just a simple test. So make sure you have an active server running via php artisan serve and then just put up the endpoints that we defined in api.php; We have the following:

/api/pay-with-paypal
/api/pay-with-stripe
/api/pay-with-squarepay

Now let's see each of these if it returns the actual implementation from each services that we defined above when creating them.

/api/pay-with-paypal

That is exactly what we wrote in PaypalService to return a string from the pay method and we even specified it with "PaypalService" just for us to indicate where the implementation is coming from. So using Contextual Binding works and it solves our problem!

/api/pay-with-stripe

And this is for Stripe.

/api/pay-with-squarepay

And our last payment provider that our client wants. We got it.

Conclusion

Now that we learned how to tackle multiple payment providers using the Inversion of Control (IoC) principle, we learned how to implement it with Laravel's service container using Contextual Binding, and we understand that we'll always go with the best approach to address a problem. Don't use Inversion of Control when it's not really relevant solution at all, no need to add complexity. Only use it when it seems the best solution.

I hope this was useful and that you have learned something new. Thanks for taking the time to read and have a good day!

Full Source Code

Data Modeling with Flutter using freezed package

Carlo Miguel Dy — Sat, 05 Jun 2021 04:19:36 +0000

Introduction

In this post we'll cover how you can create a data model using freezed package in Flutter and learn about a few techniques that I know and have been using when building projects. We will be using JSONPlacheolder to consume a REST API with dio as our HTTP client and create a data model for the /users endpoint to the Flutter application.

Data modeling is a process of creating a visual representation of information that describes the a business entity of a software project. It is a technique that is being often used in most applications. A data model can also represent relationship between each business entities. Or if you know about relational databases then for a quick comparison, a data model can be an SQL table that represents it.

You can read more in depth about data modeling here

Installation

First we will begin with installing a fresh Flutter project, so go over and open up your terminal and execute the following command below.



flutter create freezed_data_modeling

Then open the project in your IDE (Visual Studio Code) and open up the pubspec.yaml file and add up the following dependencies that we require,

dependencies:
- freezed_annotation
dev_dependencies:
- build_runner
- freezed



dependencies:
  flutter:
    sdk: flutter
  freezed_annotation:
    dio:

  # The following adds the Cupertino Icons font to your application.
  # Use with the CupertinoIcons class for iOS style icons.
  cupertino_icons: ^1.0.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  build_runner:
  freezed:

And finally execute flutter pub get when you've added those dependencies.

Next you can launch an emulator and run the project in it, but you can do it later.

JSONPlaceholder response

Before we start creating our data models, we should know what resources are getting returned to the application. It wouldn't make sense to create data models when the data model you created does not reflect in the backend. Take a look at it carefully and identify which properties are of type String , double , int , and etc.



// https://jsonplaceholder.typicode.com/users
[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
      "name": "Romaguera-Crona",
      "catchPhrase": "Multi-layered client-server neural-net",
      "bs": "harness real-time e-markets"
    }
  },

  ...
]

When taking a closer look at it we can identify the following,

id is of type int because it returns a single digit
name contains various characters, so this is a String
username is a String
email is a String
address is a JSON object, so we'll require to create its own data model as well because we don't wanna put up a type for that as Map<String, dynamic> that would make less robust

So let's identify the property types for each property in address field:
- street is a String
- suite is a String
- city is a String
- zipcode is a String
- geo is another JSON object, so we'll do the same thing as what we are currently doing for address
  - lat can be a String but since we know it is "latitude" and usually they are in decimal values, so we'll use double for that instead
  - lng is double
phone is a String
website is a String
company is a JSON object
- name is a String
- catchPhrase is a String
- bs is a String

Creating a data model without freezed

Usually when we start to create our data models is that we use this approach, also means that we are writing out a lot of "boilerplate" code which isn't very ideal when you have a large complex application. One could be spending a lot of time just writing up data models this way, manually adding method calls like toJson() to convert the data model into a JSON format which is the typical format we use when we are creating requests to a REST API, GraphQL API or any sort of backend service that you could be using.



class Geo {
  final double lat;
  final double lng;

  Geo({
    this.lat = 0.0,
    this.lng = 0.0,
  });

  Map<String, dynamic> toJson() {
    return {
      'lat': lat,
      'lng': lng,
    };
  }
}

class Address {
  final String? street;
  final String? suite;
  final String? city;
  final String? zipcode;

  Address({
    this.street,
    this.suite,
    this.city,
    this.zipcode,
  });

  Map<String, dynamic> toJson() {
    return {
      'street': street,
      'suite': suite,
      'city': city,
      'zipcode': zipcode,
    };
  }
}

class Company {
  final String? name;
  final String? catchPhrase;
  final String? bs;

  Company({
    this.name,
    this.catchPhrase,
    this.bs,
  });

  Map<String, dynamic> toJson() {
    return {
      'name': name,
      'catchPhrase': catchPhrase,
      'bs': bs,
    };
  }
}

class User {
  final int id;
  final String? username;
  final String? email;
  final Address? address;
  final String? phone;
  final String? website;
  final Company? company;

  User({
    required this.id,
    this.username,
    this.email,
    this.address,
    this.phone,
    this.website,
    this.company,
  });

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'username': username,
      'email': email,
      'address': address?.toJson(),
      'phone': phone,
      'website': website,
      'company': company?.toJson(),
    };
  }
}

This would take up a lot of your time and could even be counterproductive for you as a developer.

Also notice how I am putting up with the ? annotation in each of the properties since they could potentially be null and that would be considered a bug and will produce crashes in the application during run time or if when our users are using our application.

You can learn more about null-safety here

There are quite a lot of problems that this gives us when writing our applications since there comes a point where when we will have to copy all values and replace with a new value. In JavaScript we can simply do that with the "triple dot" notation to create a new object from an existing object.



const person = {
  name: "Carlo Miguel Dy",
  age: 23,
}

console.log(person)
// { "name": "Carlo Miguel Dy", "age": 23 }

const newPerson = {
  ...person,
  name: "John Doe",
}

console.log(newPerson)
// { "name": "John Doe", "age": 23 }

But unfortunately we can't do that with Dart yet. We can do that but it's quite a lot of "boilerplate" code.

Creating a data model with freezed

A lot of the "boilerplate" code is eliminated when we are using the freezed package, what it does is it generates all those "boilerplate" code for us, we can also make use of its annotations which comes very handy. To mention a few these are @Default for providing a default value when this property is null and we also use @JsonKey to override the JSON key just in case the conventions is different from the backend. Some do use camelCasing , snake_casing and PascalCasing so these are the kind of problem it can solve with only a few lines of code.



import 'package:freezed_annotation/freezed_annotation.dart';

part 'freezed_datamodels.freezed.dart';
part 'freezed_datamodels.g.dart';

@freezed
class Geo with _$Geo {
  const factory Geo({
    @Default(0.0) double lat,
    @Default(0.0) double lng,
  }) = _Geo;

  factory Geo.fromJson(Map<String, dynamic> json) => _$GeoFromJson(json);
}

@freezed
class Address with _$Address {
  const factory Address({
    @Default('') String street,
    @Default('') String suite,
    @Default('') String city,
    @Default('') String zipcode,
    Geo? geo,
  }) = _Address;

  factory Address.fromJson(Map<String, dynamic> json) =>
      _$AddressFromJson(json);
}

@freezed
class Company with _$Company {
  const factory Company({
    @Default('') String name,
    @Default('') String catchPhrase,
    @Default('') String bs,
  }) = _Company;

  factory Company.fromJson(Map<String, dynamic> json) =>
      _$CompanyFromJson(json);
}

@freezed
class User with _$User {
  const factory User({
    required int id,
    required String username,
    required String email,
    Address? address,
    @Default('') String phone,
    @Default('') String website,
    Company? company,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

We only have to write a few lines of code to create the data models and we are utilizing on the annotations that the freezed package provides for us.

To break down each data model I defined above for you,

Geo
- The lat property is non-nullable but has a default value of 0.0 when this value is empty
- The lng property is non-nullable but has a default value of 0.0 when this value is empty
Address
- The street property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
- The suite property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
- The city property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
- The zipcode property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
Company
- The name property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
- The catchPhrase property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
- The bs property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
User
- The id property is non-nullable but is required and this property should never be null
- The username property is non-nullable but is required and this property should never be null
- The email property is non-nullable but is required and this property should never be null
- The address property is nullable
- The phone property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
- The website property is non-nullable but has a default value of '' which means it will be an empty string when this value is empty
- The company property is nullable

Generating code using build_runner package

As the code snippet above you will notice that we have 2 lines of code that uses part and it contains freezed and g these are the ones that will let freezed package to recognize that it requires to generate a code whenever we execute the build_runner to build generate code for us.

To start generating code for us, execute the following command with-in the root directory of your Flutter project.



flutter pub run build_runner build --delete-conflicting-outputs

To break it down what each does, the flutter pub run will allow us to run script coming from a package like build_runner and the build is the command or script to tell the build_runner package to start generating code for us. It will look for files that contains the following *.freezed.dart and *.g.dart the * is just a wild card that means any file name that contains it will be recognized by the build_runner and lastly the --delete-conflicting-outputs flag will tell the build_runner package to delete any existing *.freezed.dart and *.g.dart files to prevent duplicate outputs or that it could potentially conflict with those.

So every time you might have to update your data model with new properties, you will always have to execute this the command snippet above to tell build_runner to generate code for us.

You can take a peek at what code was generated from the repository or directly from the links below:

Copying values from a data model but only change values of specific properties

Coming back with copying values of an object in JavaScript, we can now simply do that as well with our data model that is using the freezed package.



final person = User(
  id: 1,
  username: 'carlomigueldy',
  email: 'carlomigueldy@gmail.com',
);

person.toJson();
// { "id": 1, "username": "carlomigueldy", "email": "carlomigueldy@gmail.com", ... }

final newPerson = person.copyWith(
  username: 'johndoe123',
);

newPerson.toJson();
// { "id": 1, "username": "johndoe123", "email": "carlomigueldy@gmail.com", ... }

That's really powerful.

Consuming the REST API

We just got a basic application installed, so remove all those comments that make the code too long in main.dart file.



import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: Icon(Icons.add),
      ),
    );
  }
}

Create a final field with type Dio and instantiate it with a new Dio instance, then create a function called fetchUsers that will fetch data from this endpoint https://jsonplaceholder.typicode.com/users and set it in a private property with type List<User> called as _users , we can call this function when you will click on the FloatingActionButton or for call this function inside the initState lifecycle hook of a StatefulWidget , for convenience I will just have the code here below for you to reference on if you prefer to write it out yourself. But the full source code will be found in the repository for a better reference.



class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final Dio dio = Dio();
  List<User> _users = [];

  Future<void> fetchUsers() async {
    final response = await dio.get(
      'https://jsonplaceholder.typicode.com/users',
    );
    print(response.data);
    final List list = response.data;

    setState(() {
      _users = list.map((e) => User.fromJson(e)).toList();
    });
  }

  @override
  void initState() {
    fetchUsers();

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: ListView.builder(
        itemCount: _users.length,
        itemBuilder: (context, index) {
          final user = _users[index];

          return ListTile(
            title: Text(user.username),
            subtitle: Text(user.email),
          );
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: fetchUsers,
        tooltip: 'Fetch Users',
        child: Icon(Icons.data_usage),
      ),
    );
  }
}

When you have this correctly in your code then it should look very similar to this screenshot.

Using "copyWith" method from a data model

Now let's make it a bit interesting, this is not a very practical approach when building out your applications but it will give you an idea and on how you can make use of this. There are a lot of use cases that you might require to use copWith method from a freezed data model.

For the sake of demonstration purposes, we will implement the following for when a user taps on any of the ListTile under the ListView we will change the value of the username property and append a string with value of " CLICKED", so for instance when "Bret" is tapped then we will have it display "Bret CLICKED". To put things into action, let's create a function that will take an argument as the index of that item of a ListTile then attach it on to the onTap property of a ListTile and just pass in the current index of that item.



void appendUsername(int index) {
    setState(() {
      _users[index] = _users[index].copyWith(
        username: '${_users[index].username} CLICKED',
      );
    });
  }

// ... 

body: ListView.builder(
        itemCount: _users.length,
        itemBuilder: (context, index) {
          final user = _users[index];

          return ListTile(
            title: Text(user.username),
            subtitle: Text(user.email),
            onTap: () => appendUsername(index),
          );
        },
      ),

Then we'll have the following output when any of the ListTile is tapped.

Example usage for `@JsonKey` annotation

There are certain cases that we can make use of @JsonKey annotation when creating our data models, say we have this data model and we have a property named as catchPhrase when this gets generated from the build_runner package, the JSON property will be equivalent to catchPhrase so basically it will result to something like this json['catchPhrase']

In the current API we will be consuming, there'd be no problem since it uses camelCasing convention so we can just have that as is

But what happens if the API will have different set of conventions, and we don't do something about it, so eventually our property catchPhrase in our Company data model will always be null since it will never match CatchPhrase or catch_phrase that is returned in the application when it is trying to retrieve its value by json['catchPhrase']



@freezed
class Company with _$Company {
  const factory Company({
    @Default('') String name,
    @Default('') String catchPhrase,
    @Default('') String bs,
  }) = _Company;

  factory Company.fromJson(Map<String, dynamic> json) =>
      _$CompanyFromJson(json);
}

So to fix that we will make use of the @JsonKey annotation, just add it before the @Default annotation in this case, then we can specify the JSON object property name like so



@freezed
class Company with _$Company {
  const factory Company({
    @Default('') String name,
    @JsonKey(name: 'catch_phrase') @Default('') String catchPhrase,
    @Default('') String bs,
  }) = _Company;

  factory Company.fromJson(Map<String, dynamic> json) =>
      _$CompanyFromJson(json);
}

Then whenever we call Company.fromJson(json) it will parse that coming from a JSON format into the actual Company data model that we defined into our application. Instead of having it retrieve by json['catchPhrase'] we now retrieving it by what we defined in the name property of the @JsonKey annotation so in this case it will be json['catch_phrase']

I hope that makes sense.

Another way of how we can make use of it is when we require to convert a property into a JSON format. For example, for our User data model it contains a property for Company data model and an Address data model. So when we print it out we will have the following value.



// Where `user` is of type `User`

print(user.toJson());
// {id: 4, username: Karianne, email: Julianne.OConner@kory.org, address: Address(street: Hoeger Mall, suite: Apt. 692, city: South Elvis, zipcode: 53919-4257), phone: 493-170-9623 x156, website: kale.biz, company: Company(name: Robel-Corkery, catchPhrase: Multi-tiered zero tolerance productivity, bs: transition cutting-edge web services)}

You will notice that the address property is not in its JSON format, it has the following value instead which tells us it is a class with the its corresponding property and values. Which isn't very ideal whenever we will have to pass this information back into the API, it will throw an exception instead. But this doesn't happen to often when you have to pass back a huge payload to the API.



address: Address(street: Hoeger Mall, suite: Apt. 692, city: South Elvis, zipcode: 53919-4257)

The way we can fix that up is by using the property fromJson and toJson converters from the @JsonKey annotation. We declare it again before the @Default annotation when there exists, otherwise it's just the same spot before the actual property.



@freezed
class User with _$User {
  const User._();
  const factory User({
    required int id,
    required String username,
    required String email,
    @JsonKey(
      fromJson: User._addressFromJson,
      toJson: User._addressToJson,
    )
        Address? address,
    @Default('')
        String phone,
    @Default('')
        String website,
    @JsonKey(
      fromJson: User._companyFromJson,
      toJson: User._companyToJson,
    )
        Company? company,
  }) = _User;

  static Address? _addressFromJson(Map<String, dynamic>? json) {
    if (json == null) return null;

    return Address.fromJson(json);
  }

  static Map<String, dynamic>? _addressToJson(Address? address) {
    if (address == null) return null;

    return address.toJson();
  }

  static Company? _companyFromJson(Map<String, dynamic>? json) {
    if (json == null) return null;

    return Company.fromJson(json);
  }

  static Map<String, dynamic>? _companyToJson(Company? company) {
    if (company == null) return null;

    return company.toJson();
  }

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

To break it down for you,

The address we used the @JsonKey annotation and passed down the properties for fromJson with what we defined as a static member of the class which returns the same type of what the property address has (Address?) which is of type Address but is nullable. As per freezed package instructions on accessing the same member of the class, it is required that we will have to call this const User._();



@freezed
class User with _$User {
  const User._();

  const factory User({
      // ...
    @JsonKey(
      fromJson: User._addressFromJson,
      toJson: User._addressToJson,
    )
        Address? address,
        // ...
  }) = _User;

  static Address? _addressFromJson(Map<String, dynamic>? json) {
    if (json == null) return null;

    return Address.fromJson(json);
  }

  static Map<String, dynamic>? _addressToJson(Address? address) {
    if (address == null) return null;

    return address.toJson();
  }

    // ...
}

The private static method _addressFromJson takes a first argument of type Map<String, dynamic> which represents a JSON value and is nullable, then in this method we check if the json argument is null and if that evaluates to true then we'll just return null otherwise we can call Address.fromJson(json) and have it return an instance of a data model Address that we defined.



static Address? _addressFromJson(Map<String, dynamic>? json) {
    if (json == null) return null;

    return Address.fromJson(json);
  }

The private static method _addressToJson takes a first argument of type Address which the data model that we defined is nullable, then in this method we check if the address argument is null and if that evaluates to true then we'll just return null otherwise we can call address.toJson() and have it return a JSON representation of it.



static Map<String, dynamic>? _addressToJson(Address? address) {
    if (address == null) return null;

    return address.toJson();
  }

Finalizing our data models



import 'package:freezed_annotation/freezed_annotation.dart';

part 'freezed_datamodels.freezed.dart';
part 'freezed_datamodels.g.dart';

@freezed
class Geo with _$Geo {
  const factory Geo({
    @Default(0.0) double lat,
    @Default(0.0) double lng,
  }) = _Geo;

  factory Geo.fromJson(Map<String, dynamic> json) => _$GeoFromJson(json);
}

@freezed
class Address with _$Address {
  const Address._();
  const factory Address({
    @Default('')
        String street,
    @Default('')
        String suite,
    @Default('')
        String city,
    @Default('')
        String zipcode,
    @JsonKey(
      fromJson: Address._geoFromJson,
      toJson: Address._geoToJson,
    )
        Geo? geo,
  }) = _Address;

  static Geo? _geoFromJson(Map<String, dynamic>? json) {
    if (json == null) return null;

    return Geo.fromJson(json);
  }

  static Map<String, dynamic>? _geoToJson(Geo? geo) {
    if (geo == null) return null;

    return geo.toJson();
  }

  factory Address.fromJson(Map<String, dynamic> json) =>
      _$AddressFromJson(json);
}

@freezed
class Company with _$Company {
  const factory Company({
    @Default('') String name,
    @Default('') String catchPhrase,
    @Default('') String bs,
  }) = _Company;

  factory Company.fromJson(Map<String, dynamic> json) =>
      _$CompanyFromJson(json);
}

@freezed
class User with _$User {
  const User._();
  const factory User({
    required int id,
    required String username,
    required String email,
    @JsonKey(
      fromJson: User._addressFromJson,
      toJson: User._addressToJson,
    )
        Address? address,
    @Default('')
        String phone,
    @Default('')
        String website,
    @JsonKey(
      fromJson: User._companyFromJson,
      toJson: User._companyToJson,
    )
        Company? company,
  }) = _User;

  static Address? _addressFromJson(Map<String, dynamic>? json) {
    if (json == null) return null;

    return Address.fromJson(json);
  }

  static Map<String, dynamic>? _addressToJson(Address? address) {
    if (address == null) return null;

    return address.toJson();
  }

  static Company? _companyFromJson(Map<String, dynamic>? json) {
    if (json == null) return null;

    return Company.fromJson(json);
  }

  static Map<String, dynamic>? _companyToJson(Company? company) {
    if (company == null) return null;

    return company.toJson();
  }

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

Then as changes were made, we can then generate a new code so let's tell build_runner to do that for us by executing it again in your terminal, run the following command



flutter pub run build_runner build --delete-conflicting-outputs

Conclusion

Cheers you have made it to this very last part! 🎉 Hope you enjoyed and learned something from this, should help you out when you strive to write clean code with-in your codebase.

We learned how we can create data models using the freezed package, we learned how we can make use of @JsonKey and creating a JSON converter for a specific field, we learned how we can use copyWith method to copy existing values and only replace the values that are specified in the parameters, and we learned how we can deal with any backend that returns different naming conventions for their JSON properties (camelCasing, snake_casing and PascalCasing). We may have only learned the basic of it and we can of course refactor some of it, but maybe we can tackle that next time, for now we are just going to make it work and that solves our problem.

If you liked this and find it useful, don't forget to show some love now hit up the like button! 💪 See you on the next one.

💻 Full source code can be found in here

Building a simple Grocery App in Flutter with Supabase

Carlo Miguel Dy — Fri, 30 Apr 2021 00:35:50 +0000

Introduction

In this article I will show you how you can build an application using Flutter with Supabase as a backend. Supabase is a Firebase alternative which uses Postgres, so that's something different and that's even amazing. Postgres is also a relational database which is also open source and a powerful tool.

We will learn and build a simple grocery application using Flutter with Supabase.

I am not going to go over setting up Flutter step by step since how I built it uses the Stacked architecture which follows an MVVM style so I will just show you how to write Supabase code in Dart with-in a Flutter application instead.

You can learn more about Stacked architecture at FilledStacks :D

My repository for SupaGrocery will be shared at the end of this tutorial. So you can go ahead and download it.

Demo

Database Design

But before we start everything else, we'll take a look at our database design. See attached image below.

For our simple grocery app, we'll only require 4 of these tables.

app_users: This is the table where we will store our users, it will have the same primary ID with the supabase auth users. I was not able to use just the users table since it cannot be read publicly so I had to create this table.
groceries: All the grocery list of each user will be stored in this table.
products: All of the products created by the user will be stored in this table.
grocery_products: This is where we sort of link the products with a grocery. This is what we call a pivot table.

Relationships

In relation databases, table relationships are very common thing and is what I love the most about in relational databases.

These two are the most common relationships:

One to One
One to Many
Many to Many (Pivot table)

Our app_users table has a One to Many relationship with the two tables we created namely products and groceries since a user can have many grocery listing and can also have many products in that grocery listing.

Then for our groceries table we have the created_by column as a foreign key so that will link to the app_users table which will then identify it as part of the user's grocery listing in our application.

The same goes for products table with the created_by column as a foreign key as well.

Then for our pivot table which is a Many to Many relationship, because a grocery listing can have many products and a product can belong to many grocery listing.

Supabase setup

Create your first Supabase account! Head over to https://supabase.io/ that is their official website.

Should take you to this wonderful dark themed site :D

Now go ahead and click that button "Start your project"

It will show you this auth0 page, so just continue with GitHub to get you registered in no time!

Then just sign in with your GitHub credentials.

Once you are done with creating your first account, you might already be in your dashboard which will have a listing of all your projects created in Supabase.

Now click on "New Project" and select any organization as you wish. I'll just select "Personal" which I modified.

When taken to this page, just fill in the following fields:

Name: "Grocery App"
Database Password: "s0m3Str0ng_PassWord!@#" (You should use your own password)
Region: (Select anything that is near you)

When that is done click on "Create new project"!

It will then redirect you to this page.

It will take a few minutes, so please wait :)

Creating Tables

When the Supabase is setup and you have created a new project. It shall take you up into this page.

Now let's click on "Create a new table"

We'll put up all the details on what we have from our database design so this setup should be pretty quick.

What I would suggest is to uncheck "Include primary key" and just add a primary key later on when the table is created. There is some sort of bug which I cannot have a default value for the uuid key to just generate a uuid when a new record is created.

Then just click on "Save" at the upper right corner to finally create the table.

When that table is created, we can proceed to add our primary key which is a uuid. Click ahead on that plus icon to add a new column for the table.

Then name the column as id and it will be a primary key and a type of uuid then have the default value "Automatically generate UUID" and click "Save" once that is done.

Once that is done, we can proceed to create more of those columns that we defined from our database design.

Next is we will create a table for products and we'll have a foreign key setup with this table since a product belongs to a user. So we'll learn how to do that quickly.

So given that you already created a primary key id and its corresponding column name as a varchar, let's create one last field which is created_by and setup this as a foreign key that links up with the app_users table.

Now click on "Add foreign key relation" button at the bottom

Then select the table app_users and the id field, when that is done click "Save"

Should then show you it is now linked up with the app_users table, so that is pretty amazing.

That is all you need to know for setting up foreign keys. Now the rest of the tables is up to you now. You got this!

Flutter Datamodels

We will be setting up our data models using freezed package with json_serializable and make sure to have a builder_runner setup in your project.

The following is our application datamodels



import 'package:freezed_annotation/freezed_annotation.dart';

part 'application_models.freezed.dart';
part 'application_models.g.dart';

@freezed
class AppUser with _$AppUser {
  const factory AppUser({
    required String id,
    required String name,
    required String email,
  }) = _AppUser;

  factory AppUser.fromJson(Map<String, dynamic> json) =>
      _$AppUserFromJson(json);
}

@freezed
class Grocery with _$Grocery {
  const Grocery._();
  const factory Grocery({
    required String id,
    required String name,
    @JsonKey(name: 'created_by')
        required String createdBy,
    @Default([])
    @JsonKey(
      name: 'grocery_products',
      fromJson: Grocery._productsFromJson,
      toJson: Grocery._productsToJson,
    )
        List<GroceryProduct>? groceryProducts,
  }) = _Grocery;

  bool get hasGroceryProducts => groceryProducts!.length > 0;

  List<Product?>? get products {
    if (!hasGroceryProducts) return [];

    return groceryProducts!.map((e) => e.product).toList();
  }

  factory Grocery.fromJson(Map<String, dynamic> json) =>
      _$GroceryFromJson(json);

  static List<GroceryProduct>? _productsFromJson(List<dynamic>? list) {
    if (list == null) {
      return [];
    }

    return list.map((e) => GroceryProduct.fromJson(e)).toList();
  }

  static List<Map<String, dynamic>>? _productsToJson(
      List<GroceryProduct>? list) {
    if (list == null) {
      return [];
    }

    return list.map((e) => e.toJson()).toList();
  }
}

@freezed
class GroceryDto with _$GroceryDto {
  const factory GroceryDto({
    required String name,
    @JsonKey(name: 'created_by') required String createdBy,
  }) = _GroceryDto;

  factory GroceryDto.fromJson(Map<String, dynamic> json) =>
      _$GroceryDtoFromJson(json);
}

@freezed
class Product with _$Product {
  const factory Product({
    required String id,
    required String name,
    @JsonKey(name: 'created_by') required String createdBy,
  }) = _Product;

  factory Product.fromJson(Map<String, dynamic> json) =>
      _$ProductFromJson(json);
}

@freezed
class ProductDto with _$ProductDto {
  const factory ProductDto({
    required String name,
    @JsonKey(name: 'created_by') required String createdBy,
  }) = _ProductDto;

  factory ProductDto.fromJson(Map<String, dynamic> json) =>
      _$ProductDtoFromJson(json);
}

@freezed
class GroceryProduct with _$GroceryProduct {
  const factory GroceryProduct({
    required String id,
    @JsonKey(name: 'grocery_id') required String groceryId,
    @JsonKey(name: 'product_id') required String productId,
    required int quantity,
    @JsonKey(name: 'products') Product? product,
    @Default('') String? unit,
  }) = _GroceryProduct;

  factory GroceryProduct.fromJson(Map<String, dynamic> json) =>
      _$GroceryProductFromJson(json);
}

@freezed
class GroceryProductDto with _$GroceryProductDto {
  const factory GroceryProductDto({
    @JsonKey(name: 'grocery_id') required String groceryId,
    @JsonKey(name: 'product_id') required String productId,
    @Default(1) int quantity,
    String? unit,
  }) = _GroceryProductDto;

  factory GroceryProductDto.fromJson(Map<String, dynamic> json) =>
      _$GroceryProductDtoFromJson(json);
}

@freezed
class AuthDto with _$AuthDto {
  const factory AuthDto({
    required String email,
    required String password,
    String? name,
  }) = _AuthDto;

  factory AuthDto.fromJson(Map<String, dynamic> json) =>
      _$AuthDtoFromJson(json);
}

The code above will generate us the following files

We don't have to write everything we just let it auto generate using build_runner

To break it down for you regarding our data models, we see we have our primary tables for our grocery application

AppUser
Grocery
Product
GroceryProduct

DTOs

GroceryDto
ProductDto
GroceryProductDto
AuthDto

But what are those datamodels with "Dto" name on them?

DTO simply means Data Transfer Object, I like to use DTOs in any API request that I make.

A Data Transfer Object is an object that is used to encapsulate data, and send it from one subsystem of an application to another. DTOs are most commonly used by the Services layer in an N-Tier application to transfer data between itself and the UI layer.

Flutter Setup

Install a Flutter application and set it up. Then have the following dependencies to setup Supabase with it.

packages:

I added postgrest since I want to take all typings from the package and Supabase is using those.

When that is done, you can proceed to setting up your Supabase client



import 'package:supabase/supabase.dart';

// use your own SUPABASE_URL
const String SUPABASE_URL = 'https://borayzhhitkyveigfijz.supabase.co';

// use your own SUPABASE_SECRET key
const String SUPABASE_SECRET =
    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlhdCI6MTYxOTMwODI5MCwiZXhwIjoxOTM0ODg0MjkwfQ.Kk1ckyjzCB98aWyBPtJsoWuTsbq2wyYfiUxG7fH4yAg';

final SupabaseClient supabase = SupabaseClient(SUPABASE_URL, SUPABASE_SECRET);

These can be found from your project settings in API tab. To get the SUPABASE_URL

And the SUPABASE_SECRET

Then we can make queries when this is already setup!

Supabase Queries

If you know SQL or familiar with it, it should feel very similar.

But these will be auto generated from Supabase itself, so don't worry in case you don't know how to construct a Supabase query. Just check on the project API which will be dynamically generated for you whenever you update table or change any columns.

To compare it, this is a RAW SQL query.



SELECT * FROM products

And this is how you write queries with Supabase in Dart



supabase.from("products").select().execute();

Make sure you always have the execute at the last part otherwise it will not get all data from products table.

What about querying for a single record?

In SQL we have,



SELECT * FROM products WHERE id = "uuid-string";

In Supabase Dart we have,



supabase.from("products").select().eq("id", "uuid-string").single().execute();

There are more queries to show from your Supabase project, so be sure to check it out here

Authentication

In every application, one thing you can secure your user's data is to have an authentication system. So with Supabase it is very easy to get started with authentication right away as they provide a very simple and intuitive API!



class AuthenticationService {
  final _logger = Logger();
  final _localStorageService = locator<LocalStorageService>();

  AppUser? _user = null;
  AppUser? get user => _user;
  bool get hasUser => _user != null;

  Future<void> initialize() async {}

  Future<AppUser?> signIn({required AuthDto payload}) async {}

  Future<AppUser?> signUp({required AuthDto payload}) async {}

  Future<void> signOut() async {}

  Future<AppUser?> fetchUser({required String id}) async {}

  Future<PostgrestResponse> _createUser(User user, AuthDto payload) {}
}

To the code above, to break it down. This is dependent with the local storage service (Shared Preferences) which is where we will store out JWT auth token / refresh token and the Logger which can be useful for debugging. So I like to have a Logger with me.

We have a private propery _user which is where we store our user with its own getter and a boolean getter to check if the user is logged in if the _user property is not null.

Inside the initialize() method is where we will perform auto login. So if the user has a refresh token stored in their local storage, we will proceed to login this user and get user data and store it in _user property so the hasUser boolean getter will be true.



Future<void> initialize() async {
    final accessToken = await _localStorageService.getItem('token');
    _logger.i(accessToken);

    if (accessToken == null) {
      return;
    }

    final response = await supabase.auth.api.getUser(accessToken);

    if (response.error != null) {
      return;
    }

    final user = response.data!;
    _logger.i(user.toJson());
    await fetchUser(id: user.id);
  }

Next is the signIn method which has an argument of AuthDto that contains email and password field. When a user provided correct and existing email, we will take their access token and store it in local storage.



Future<AppUser?> signIn({required AuthDto payload}) async {
    final response = await supabase.auth.signIn(
      email: payload.email,
      password: payload.password,
    );

    if (response.error != null) {
      _logger.e(response.error!.message);
      return null;
    }
    _logger.i(response.data);
    await _localStorageService.setItem('token', response.data!.accessToken);
    return await fetchUser(id: response.data!.user!.id);
  }

We use the signUp method whenever we have a new user that wants to use our app. When a new user is created, we take the access token and save it to local storage. We will also proceed to creating a new user record in the app_users table but it will be in a different method called _createUser



Future<AppUser?> signUp({required AuthDto payload}) async {
    final response =
        await supabase.auth.signUp(payload.email, payload.password);

    if (response.error != null) {
      _logger.e(response.error!.message);
      return null;
    }

    final user = response.data!.user!;
    _logger.i(user.toJson());
    await _createUser(user, payload);
    await _localStorageService.setItem('token', response.data!.accessToken);
    return await fetchUser(id: user.id);
  }

_createdUser will create a new user record inside app_users table.



Future<PostgrestResponse> _createUser(User user, AuthDto payload) {
    return supabase
        .from("app_users")
        .insert(
          AppUser(
            id: user.id,
            name: payload.name!,
            email: user.email,
          ),
        )
        .execute();
  }

Then the signOut which is already self explanatory. Here we just remove the access token from the local storage when user decides to signOut



Future<void> signOut() async {
    final response = await supabase.auth.signOut();

    if (response.error != null) {
      _logger.e(response.error!.message);
      return;
    }
    _logger.i(response.rawData);
    await _localStorageService.removeItem('token');
    return;
  }

And lastly we have the fetchUser method, that will fetch the user record that is currently authenticated so we'll have their information across the entire application whenever we need it.



Future<AppUser?> fetchUser({required String id}) async {
    final response = await supabase
        .from("app_users")
        .select()
        .eq('id', id)
        .single()
        .execute();

    _logger.i(
      'Count: ${response.count}, Status: ${response.status}, Data: ${response.data}',
    );

    if (response.error != null) {
      _logger.e(response.error!.message);
      return null;
    }

    _logger.i(response.data);
    final data = AppUser.fromJson(response.data);
    _user = data;

    return data;
  }

Supabase Service

We finished handling our data models and authentication, then we can create and handle read write operations for our application. Thanks to the concept of abstraction, we don't have to write up a lot of code for the same functionality, we will be writing less code and have this functionality extended to other service that requires it.

The following will be the abstract class that handles CRUD operations (Cread, Read, Update, Delete)



import 'package:logger/logger.dart';
import 'package:postgrest/postgrest.dart';
import 'package:supagrocery/app/app.locator.dart';
import 'package:supagrocery/app/supabase_api.dart';
import 'package:supagrocery/services/authentication_service.dart';

abstract class SupabaseService<T> {
  final _authService = locator<AuthenticationService>();
  final _logger = Logger();

  String tableName() {
    return "";
  }

  Future<PostgrestResponse> all() async {
    _logger.i(tableName());
    final response = await supabase
        .from(tableName())
        .select()
        .eq('created_by', _authService.user!.id)
        .execute();
    _logger.i(response.toJson());
    return response;
  }

  Future<PostgrestResponse> find(String id) async {
    _logger.i(tableName() + ' ' + id);
    final response = await supabase
        .from(tableName())
        .select()
        .eq('id', id)
        .single()
        .execute();
    _logger.i(response.toJson());
    return response;
  }

  Future<PostgrestResponse> create(Map<String, dynamic> json) async {
    _logger.i(tableName() + ' ' + json.toString());
    final response = await supabase.from(tableName()).insert(json).execute();
    _logger.i(response.toJson());
    return response;
  }

  Future<PostgrestResponse> update({
    required String id,
    required Map<String, dynamic> json,
  }) async {
    _logger.i(tableName() + ' ' + json.toString());
    final response =
        await supabase.from(tableName()).update(json).eq('id', id).execute();
    _logger.i(response.toJson());
    return response;
  }

  Future<PostgrestResponse> delete(String id) async {
    _logger.i(tableName() + ' ' + id);
    final response =
        await supabase.from(tableName()).delete().eq('id', id).execute();
    _logger.i(response.toJson());
    return response;
  }
}

This abstract class has a dependency on the AuthenticationService that we just created so we'll be able to attach the user's ID every time they create records in our database.

And we'll have the tableName to override for each feature services that requires it. So when creating our ProductService and GroceryService, we simply extend this class and that override tableName with their corresponding table names.

This is an example for ProductService



import 'package:postgrest/postgrest.dart';
import 'package:supagrocery/app/app.locator.dart';
import 'package:supagrocery/app/supabase_api.dart';
import 'package:supagrocery/datamodels/application_models.dart';
import 'package:supagrocery/services/authentication_service.dart';
import 'package:supagrocery/services/supabase_service.dart';

class ProductService extends SupabaseService<Product> {
  final _authService = locator<AuthenticationService>();

  @override
  String tableName() {
    return "products";
  }

  Future<PostgrestResponse> fetchProducts() async {
    return await supabase
        .from("products")
        .select("*")
        .eq('created_by', _authService.user!.id)
        .execute();
  }
}

This will also have the methods from SupabaseService abstract class that we created and won't have to rewrite anything of it, we only need to override the tableName and return the name of that table. With that inside the ProductService we can then write up any method that is relevant to the business logic.

Then this is our GroceryService



import 'package:postgrest/postgrest.dart';

import 'package:supagrocery/app/app.locator.dart';

import 'package:supagrocery/app/supabase_api.dart';

import 'package:supagrocery/datamodels/application_models.dart';

import 'package:supagrocery/services/supabase_service.dart';

import 'authentication_service.dart';

class GroceryService extends SupabaseService<Grocery> {

  final _authService = locator<AuthenticationService>();

@override

  String tableName() {

    return "groceries";

  }

Future<PostgrestResponse> fetchGroceryList({required String id}) async {

    return await supabase

        .from("groceries")

        .select(", grocery_products(, products(*) )")

        .eq('id', id)

        .eq('created_by', _authService.user!.id)

        .single()

        .execute();

  }

Future<PostgrestResponse> addProductsToList({

    required String id,

    required List<Product?> products,

  }) async {

    return await supabase

        .from("grocery_products")

        .insert(

          products.map((e) {

            return GroceryProductDto(

              groceryId: id,

              productId: e!.id,

            ).toJson();

          }).toList(),

        )

        .execute();

  }

Future<PostgrestResponse> markProductChecked(

      {required GroceryProduct payload}) async {

    return await supabase

        .from("grocery_products")

        .update(payload.toJson())

        .eq('id', payload.id)

        .execute();

  }

Future<PostgrestResponse> removeProduct({required String id}) async {

    return await supabase

        .from("grocery_products")

        .delete()

        .eq('id', id)

        .execute();

  }

}

Summary

We covered database design, setting up Supabase, implementing an authentication system with Supabase API, and using abstraction to easily implement new features.

I hope this gave you an idea and was useful in any sort of way.

Thanks for reading and hope you enjoyed!

Link to Repository

Building a simple blog site with Next.js + Strapi API

Carlo Miguel Dy — Mon, 12 Apr 2021 23:54:50 +0000

Introduction

We'll learn how we can build a blog site with Next.js and Strapi as our Headless CMS. With these two technologies combined, you can already have a blog up and ready as quickly as you can. So if you have opened this article so I assume you understand or familiar with the basics of React / Next js. With that all said, let's get started.

File Structure

This is going to be a monorepo so we can easily navigate through our backend (Strapi) and the frontend (Next.js).

Let's just have this simple file structure



- backend
- frontend
README.md

Installation

Open your terminal and create a directory



$ mkdir nextjs-strapi-blog

Then navigate into that directory and install Strapi and Next.js. For now let's put the --quickstart flag, this basically just selects the database which will be SQLite and other default configurations just to setup our Strapi backend quick.

And of course, we can use any other SQL databases with Strapi.



$ npx create-strapi-app backend --quickstart

It will then take awhile for the Strapi installation so wait up for about 5 minutes maximum or less. Once that is done it will launch a page and asks you to create an admin account.

Just create a simple account that is easy to remember, for example:



First Name: Admin
Last Name: Admin
Email: admin@admin.com
Password: Password123!

Once that is done, the Strapi Admin dashboard should be opened by now.

Then up next will be to create our Next.js app



$ npx create-next-app frontend

After installing Next.js let's add TypeScript for our Next.js



$ touch tsconfig.json

Then run the app and it should throw us an error in the CLI and will ask us to install the following



# If you’re using npm
$ npm install --save-dev typescript @types/react @types/node

# If you’re using Yarn
$ yarn add --dev typescript @types/react @types/node

Once that is done we can run our Next.js server again and it should be ready. Then all of our files will end with .tsx so we can use TypeScript in writing code and it will be much easier for us to write code for the application.

Creating a Post Collection

For a single post in our blog application, we'll have the following fields like title, and content. So that's all we have for now we'd like to keep it simple since this is just a simple blog application.

For our TypeScript datamodel, we'll have something like



export interface Post {
  id: number;
  title: string;
  content: string;
  created_at: any;
  updated_at: any;
  published_at: any;
}

The other fields like id, created_at and published_at are being generated by Strapi.

So let's proceed to creating a Collection Type in Strapi. Now on the side menu / sidebar, hover over the "Content-Types Builder" and click it and it should navigate us to this page.

Once you are already in that page, then click on "Create new collection type"

A modal should then open with a field labelled as "Display Name", then just put "Post",

We want it to be in a form of a singular word than plural because Strapi will then read this as plural word when generating API endpoints. So basically if we have a Collection named as "Post" then our RESTful API endpoints that are generated will have /posts, and /posts/:id.

Click "Continue" to proceed.

While we only have two fields for this Collection, we simply want "Text" for our title field and "Rich Text" for the content.

Once that is done, click on "Save"

And after that, we already have a REST API that was generated by Strapi itself! We will also have the following CRUD feature up and ready, so let's visit the page under Strapi dashboard.

Then we can create a few posts then we'll test our API.

Creating Posts

Click the "Create" button on the top right portion and you should then navigate into this page with the form.

Click "Save" when done, then wait a bit and finally click "Publish" so we can see this getting returned from the REST API when we are requesting the data.

Allow read access to Public

Before anything else, we will have to allow reads. To do that, navigate into "Settings" page and click on the "Roles" tab under "Users & Permissions Plugin" section. Then on the table click on the row "Public" then we can allow reads publicly.

Once that is done be sure to click "Save", and we can proceed to testing our API manually in the browser or you can do it using Insomnia. Whichever you prefer.

Testing

Just to make it quick and easy because it's just basically the same thing. Open this in a new tab http://localhost:1337/posts and it should return an array of objects.

Frontend

We can setup our frontend and make it read the posts that is created from Strapi. But before that I'll want to use axios for HTTP calls.

So to install on a new fresh terminal and make sure you are under frontend directory



$ cd frontend

Then install the package



$ npm install axios

For the look, let's use Chakra UI. To install it,



$ npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4

Then make the following changes of your Next application if you haven't already.

Change _app.js to _app.tsx then add the AppProps type on the first destructured parameter.

Then the index.js page to index.tsx.

The moving back under _app.tsx file, wrap the <Component {...pageProps} /> around the component ChakraProvider

It should then look like this when done correctly.



import { ChakraProvider } from "@chakra-ui/react";
import { AppProps } from "next/dist/next-server/lib/router/router";

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

export default MyApp;

Then the index.tsx file, remove everything from there and replace the following code:



import { GetServerSideProps, GetStaticProps } from "next";
import axios from "axios";
import { Box, Heading } from "@chakra-ui/layout";

interface Post {
  id: number;
  title: string;
  content: string;
  created_at: any;
  updated_at: any;
  published_at: any;
}

interface PostJsonResponse {
  data: Post[];
}

export const getStaticProps: GetStaticProps = async () => {
  const response = await axios.get("http://localhost:1337/posts", {
    headers: {
      Accept: "application/json",
    },
  });
  const data: Post[] = response.data;

  return {
    props: {
      data,
    },
  };
};

const IndexView = ({ data }: PostJsonResponse) => {
  return (
    <>
      <Box height="100vh" padding="10">
        <Heading>My Blog</Heading>
        <pre>{JSON.stringify(data, null, 2)}</pre>
      </Box>
    </>
  );
};

export default IndexView;

To break it down for you. Under index.tsx file, that is our main view and the route path is /, basically this is the first page.

We created an interface of Post from the one I mentioned above and a PostJsonResponse as we'll provide that type to the first parameter of our React component which is the props.

We also used getStaticProps for fetching data from our Strapi backend. While this is just a simple blog application and there's not many posts to create we'll use getStaticProps as it will pre generate these data during build time as JSON files. Basically making reads blazing fast.

And on the template, we used the Box component from Chakra UI just for the layout and providing us padding and a height of 100vh.

Then just to see the JSON data we called it in the template <pre>{JSON.stringify(data, null, 2)}</pre> and the pre tag just to make it look "pretty" and easier to read the JSON format.

So that's about it. So this is how it looks as of the moment.

Creating a PostCard component

Just to make things look better, let's create a PostCard component that will have an onClick prop so whenever we click on the card it will redirect us to a Post detail view to read more of the contents from each of our posts that we created from Strapi.

To do that, create a directory under frontend directory and name it as components then create the file called PostCard.tsx.

Then the code would be as follows



import { Button } from "@chakra-ui/button";
import { Box, Heading, Text } from "@chakra-ui/layout";

export type PostCardProps = {
  title: string;
  publishedAt: string;
  onClick: VoidFunction;
};

const PostCard = ({ title, publishedAt, onClick }: PostCardProps) => {
  return (
    <>
      <Box
        padding="30px"
        width="500px"
        shadow="lg"
        borderRadius="md"
        marginBottom="30px"
        onClick={onClick}
      >
        <Box display="flex" justifyContent="space-between">
          <Text fontWeight="bold" fontSize="24px">
            {title}
          </Text>
          <Button colorScheme="facebook">Read</Button>
        </Box>
        <Text size="10px">Published at {new Date(publishedAt).toLocaleDateString()}</Text>
      </Box>
    </>
  );
};

export default PostCard;

Use the PostCard component

Then head on over back to our index.tsx file and update that code that will be using the newly created dumb component. It is a dumb component since it doesn't handle any state, only receiving input props from a parent component.



import { GetServerSideProps, GetStaticProps } from "next";
import { Box, Center, Heading, VStack } from "@chakra-ui/layout";
import { useRouter } from "next/router";
import axios from "axios";
import PostCard from "../components/PostCard";

interface Post {
  id: number;
  title: string;
  content: string;
  created_at: any;
  updated_at: any;
  published_at: any;
}

interface PostJsonResponse {
  data: Post[];
}

export const getStaticProps: GetStaticProps = async () => {
  const response = await axios.get("http://localhost:1337/posts", {
    headers: {
      Accept: "application/json",
    },
  });
  const data: Post[] = response.data;

  return {
    props: {
      data,
    },
  };
};

const IndexView = ({ data }: PostJsonResponse) => {
  const router = useRouter();
  const toPostView = (id: number) => router.push(`/posts/${id}`);
  const posts = data.map((post) => (
    <PostCard
      key={post.id}
      title={post.title}
      publishedAt={post.published_at}
      onClick={() => toPostView(post.id)}
    />
  ));

  return (
    <>
      <Box height="100vh" padding="10">
        <Heading>My Blog</Heading>

        <Center>
          <VStack>{posts}</VStack>
        </Center>
      </Box>
    </>
  );
};

export default IndexView;

And our application will look like this by now.

You may notice I have imported the useRouter() hook from next/router and I have put an on click handler on to the button "Read" and that it should navigate into the post detail view. When you click on it now, it will return you a 404 error.

So let's create that view.

Post detail view

Create a new folder under pages directory and name it as posts then create a file and name it as [id].tsx where the brackets will make this view to render with dynamic route parameters. This way we can handle different Post IDs.

Then have the following code,



import { GetStaticPaths, GetStaticProps } from "next";
import { useRouter } from "next/router";
import { Post } from "../../models/Post";
import { Button } from "@chakra-ui/button";
import { Box, Divider, Heading, Text } from "@chakra-ui/layout";
import axios from "axios";

export type PostDetailViewProps = {
  data: Post;
};

export const getStaticPaths: GetStaticPaths = async () => {
  const response = await axios.get("http://localhost:1337/posts");
  const posts: Post[] = await response.data;

  const paths = posts.map((post) => {
    return {
      params: { id: String(post.id) },
    };
  });

  return {
    paths,
    fallback: false,
  };
};

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const { data } = await axios.get(`http://localhost:1337/posts/${params.id}`);

  return {
    props: {
      data,
    },
  };
};

const PostDetailView = ({ data }: PostDetailViewProps) => {
  const router = useRouter();

  return (
    <>
      <Box padding="10">
        <Button onClick={() => router.back()}>Back</Button>
        <Heading>{data.title}</Heading>
        <Text>{data.published_at}</Text>
        <Divider marginTop="10" marginBottom="10"></Divider>
        <Text>{data.content}</Text>
      </Box>
    </>
  );
};

export default PostDetailView;

To break it down for you. We used getStaticPaths to fetch all of the posts and map it down to shape as a path that next knows about. Since getStaticPaths and getStaticProps will be executed during build time and generates static content therefore it should make sense by now having called all posts inside a post detail view on getStaticPaths.

We then used getStaticProps and we have our first argument as the context but destructured it to only retrieve the params property which have access to the parameters of the current route. That's how we retrieve the id from the [id].tsx file name. While we have that we can make a call to a specific post.

Then on the template, we just added a "Back" button so we imported useRouter from next/router, next is we display the title field, published_at field and then the content. But for now I just didn't install a react markdown. Typically you should use react-markdown or any similar library to display the markdown contents properly.

This is how it looks by the way.

Summary

We learned how to build a blog using Strapi and Next.js and also understand some of the concepts Next.js has regarding getStaticProps and getStaticPaths for static site generation. By now you should be able to build out a simple blog on your own or you might a blog but has other use cases but simple CRUD functionalities are mostly required then usnig Strapi would definitely be a good pick. Otherwise if the project requires some customization, then consult Strapi's official documentation to understand/learn how you will implement it using Strapi.

If you've ever reached here at the bottom part of this article, then thank you so much for taking the time to read. Cheers and have a good day!

Full source code can be found from the repository.

Dependency Injection with Vue 3

Carlo Miguel Dy — Mon, 05 Apr 2021 09:24:10 +0000

Introduction

In this article we will be learning how to use Vue's provide and inject.

Installation

Open your terminal and create a fresh Vue project,



$ vue create vue-3-dependency-injection

Then open the scaffolded project by the CLI in your IDE.



$ cd vue-3-dependency-injection && code .

Provide

As an example, let's say our client wants to have the user's name in many places in our application. But there are many ways to do that, but the team decided to only go with provide() so it can supply data to components.

Note: The example scenario may not be so ideal but just to demo how provide() and inject() works



<template>
  <AppFirstChild />
  <AppSecondChild />
  <AppThirdChild />
</template>

<script>
import { defineComponent, provide } from "@vue/runtime-core";
import AppFirstChild from "./components/AppFirstChild.vue";
import AppSecondChild from "./components/AppSecondChild.vue";
import AppThirdChild from "./components/AppThirdChild.vue";

export default defineComponent({
  name: "App",

  components: {
    AppFirstChild,
    AppSecondChild,
    AppThirdChild,
  },

  setup() {
    provide("user", "Carlo Miguel Dy");
  },
});
</script>

<style>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
</style>

But we can just use props instead? We can definitely pass down props from Parent to child component and this child component passes down this prop to its other child components, and when that child component also has its own child components that needs the data from the root component you pass down props as well.

Actually this is a problem and things might not be that consistent across our application. So the solution to that problem is to use dependency injection with provide() and have all the nested child components use inject() to get the provided data.

Inject Dependency

The one way we can use or get the value from provide() is to use inject(). We'll import that also from @vue/runtime-core. Now let us inject the provided data from our Parent component.

For component AppFirstChild



<template>
  <h1>{{ user }}</h1>

  <AppFirstChildChild />
</template>

<script>
import { defineComponent, inject } from "vue";
import AppFirstChildChild from "./AppFirstChildChild.vue";

export default defineComponent({
  components: {
    AppFirstChildChild,
  },

  setup() {
    const user = inject("user");

    return {
      user,
    };
  },
});
</script>

As you see AppFirstChild component also has a child component. We can also use inject() to get the data provided from the root Parent component easily.

for component AppFirstChildChild



<template>

  <h1>AppFirstChildChild: {{ user }}</h1>

</template>

<script>

import { defineComponent, inject } from "vue";

export default defineComponent({

  setup() {

    const user = inject("user");

<span class="k">return</span> <span class="p">{</span>
  <span class="nx">user</span><span class="p">,</span>
<span class="p">};</span>



},

});

</script>

Provide any data

We are not only limited to provide values as string, we can pass down any type of data. It can be an array, a number, or an object.

So let us provide another data with emojis



export default defineComponent({

  name: "App",

components: {

    AppFirstChild,

    AppSecondChild,

    AppThirdChild,

  },

setup() {

    provide("user", "Carlo Miguel Dy");

    provide("emojis", {

      fire: "🔥",

      star: "⭐",

      pizza: "🍕",

    });

  },

});

Demo

Our client is happy with the functionality that we created, cheers!

Conclusion

When we want to be consistent in passing down values to other child components across our entire application, we should use provide() and inject() instead as it saves us the time and all the frustrations when just using props.

Thanks for taking the time to read, hope you had a wonderful weekend!

Getting started with Vue 3 + Pinia Store + TypeScript by building a Grocery List App

Carlo Miguel Dy — Tue, 30 Mar 2021 15:33:26 +0000

Introduction

Let's build a grocery list application using Vue 3 with Typescript and the Vue store Pinia! I just found out that Edward have tweeted about publishing the documentation for Pinia so I thought I'd share how we can create a simple application using this store.

I will only be covering the very basic implementation of the Pinia store.

Pre-Requisites

This article assumes the basic knowledge and understanding or familiarity with:

Vue 3 (Composition API)
TypeScript
Prior understanding of what State Management is

I will be using TypeScript for this application so I hope you understand at least the basic type annotations. Otherwise let's get right at it and start building this app!

Installation

If you don't have the Vue CLI installed yet then make sure to install it, or if your Vue CLI isn't updated yet then make sure it is on the latest version.



$ npm i -g @vue/cli

If you are on a Linux distro then add sudo at the beginning of the command since we are installing Vue CLI globally.

And once that is done let's ask Vue CLI to scaffold a Vue 3 project for us. Make sure you have selected Vue 3.



$ vue create vue-3-pinia-grocery-app

And once that is done navigate into the app and open the project in your IDE.



$ cd vue-3-pinia-grocery-app && code .

Then let us add our sugar, TypeScript.



$ vue add typescript

For now these are my selected options, you can choose on your own if you prefer.

Next is to install Pinia as the dependency for this project.



$ npm install pinia@next

And lastly install faker since I am kind of lazy to create forms for this tutorial and creating a form and validating it is sort of an out of scope. So to make things quick, let's just generate some random data from this faker package.



$ npm install faker
$ npm install --save @types/faker

$ npm install uuid
$ npm install --save-dev @types/uuid

Since I plan to use some fake data for quick data generation. Update your model code as I will have a method called generateFakeData() to generate an Item.



import { v4 as uuidv4 } from "uuid";
import * as faker from "faker";

export interface Item {
  id: string;
  name: string;
  description?: string;
  quantity: number;
  createdAt: Date;
  deletedAt?: Date;
}

export function generateFakeData(): Item {
  return {
    id: uuidv4(),
    quantity: Math.random(),
    name: faker.lorem.word(),
    description: faker.lorem.words(),
    createdAt: new Date(),
  };
}

And once that is done let us run our Vue application.



$ npm run serve

Data Model

Since we are building a Grocery List application then we should model our data. The core model to have is an Item.

So to define the model,



export interface Item {
  id: string;
  name: string;
  description?: string;
  quantity: number;
  createdAt: Date;
  deletedAt?: Date;
}

So under the src directory create a models directory and it's where this Item model will reside. So create a file name it as item.model.ts.

Then we'll have the following,

Pinia Setup

Open the main.ts file under the src directory and make sure to chain the following method use() and pass in createPinia() as the first parameter.



import { createPinia } from "pinia";
import { createApp } from "vue";
import App from "./App.vue";

createApp(App)
  .use(createPinia())
  .mount("#app");

Next is to create a directory and name it as store and inside it create a file called index.ts

Then to define this main store,



import { generateFakeData, Item } from "@/models/item.model";
import { defineStore } from "pinia";

export type RootState = {
  items: Item[];
};

export const useMainStore = defineStore({
  id: "mainStore",
  state: () =>
    ({
      items: [],
    } as RootState),

  actions: {
    createNewItem(item: Item) {
      if (!item) return;

      this.items.push(item);
    },

    updateItem(id: string, payload: Item) {
      if (!id || !payload) return;

      const index = this.findIndexById(id);

      if (index !== -1) {
        this.items[index] = generateFakeData();
      }
    },

    deleteItem(id: string) {
      const index = this.findIndexById(id);

      if (index === -1) return;

      this.items.splice(index, 1);
    },

    findIndexById(id: string) {
      return this.items.findIndex((item) => item.id === id);
    },
  },
});

We have defined the most basic functionality, creating, updating an deleting an item from our grocery list. And that is more done enough for getting to know how to setup Pinia as your Vue store.

Demo

This is the best looking UI... Yeah.

Demo

As you can see from this setup we are able to use the Pinia store, that we are able to add an Item, update it and delete it.

Summary

We learned how to setup Pinia with Vue 3 and TypeScript. What I like Pinia is that it is built with TypeScript already that means the store provides us all the auto-completion that we want and the reason we love about TypeScript. Pinia is also very intuitive which we notice it was very similar to how Vuex is implemented.

But there are more of its features that you can read about from the official documentation

I hope you find this useful, cheers!

Full source code can be found from the repository

How to share properties from an Interface to a new Interface with TypeScript

Carlo Miguel Dy — Tue, 30 Mar 2021 03:38:57 +0000

Introduction

I just saw somewhere in an FB Community group asking how they are able to share the properties from a User interface to a PublicUser interface.

I have answered the person who asked the question and I'd also like to share my answer in this post.

Solution

Given that you have a User interface with the following properties that describes the model/entity.

interface User {
  name: string;
  email: string;
  age?: number;
}

And you also want these properties in a new interface, for example for a Customer interface we will extend the User interface

interface Customer extends User {
  phoneNumber: string;

  address?: {
    streetAddress: string;
  } | null;
}

By doing that we will have the name, email, age fields inherited into our new interface which is the Customer interface.

So as an example I will attach a screenshot below.

To break it down for you, we created an object and gave it a type of Customer interface, so by triggering or to peek which properties are available in Visual Studio Code (with CTRL + Space) it shows that the properties from User interface are inherited over to the Customer interface.

Conclusion

With that in mind instead of having to copy all properties from the User interface and paste it into the Customer interface, we have just inherited it into the Customer interface from the User interface. So we are writing lesser code.

That's all I have. Hope this was useful!

Going Serverless with Nuxt (Composition API) + AWS Amplify + TypeScript

Carlo Miguel Dy — Mon, 29 Mar 2021 04:39:52 +0000

Introduction

In this article we will be learning how we can integrate AWS Amplify with-in a Nuxt app. We will be going over from setting up an AWS account (but not covered, will give you a link instead) and until we can create and fetch all Todos. The app that we will be building for this tutorial is just a basic Todo app, since the scope of this tutorial is to teach you how you will be able to use AWS Amplify with Nuxt.

I prefer to use TypeScript in this article, but you can still use just plain JavaScript whichever you prefer still results to same Todo app we will be building. But before we continue, let us understand what is Serverless? What does it actually mean?

Serverless does not mean there are no servers. There are still servers that run on the cloud but we don't manage them, meaning we don't have to deal with deploying web servers using Nginx or Apache2, we don't have to provision AWS EC2 instances or GCP Compute Engine instances, we only have to worry about directly to the business logic of the application. Isn't that cool?

For more explanation I will quote a definition from Cloudflare:

Serverless computing is a method of providing backend services on an as-used basis. A serverless provider allows users to write and deploy code without the hassle of worrying about the underlying infrastructure. A company that gets backend services from a serverless vendor is charged based on their computation and do not have to reserve and pay for a fixed amount of bandwidth or number of servers, as the service is auto-scaling. Note that despite the name serverless, physical servers are still used but developers do not need to be aware of them.

Taken from source

Setting up an AWS Account

You can skip this step if you already have setup an AWS account. Otherwise go to this URL https://aws.amazon.com/console/ and proceed to creating your AWS account! And click on the button that says "Create a Free Account". You will need a credit card to setup your AWS account otherwise you can't create one.

I am not going to go over how to setup an AWS account in here since it is an out of scope for this tutorial. But I will give you some links for my recommendation.

Also make sure to create an IAM user since AWS best practices for security is to not use the root user, instead create an IAM user and give it admin privileges and this is the only account you will be using from now on. You will only use the root user to create an admin user for your AWS account.

Installing AWS Amplify CLI

Once you are done with setting up your AWS account, let us then proceed to installing the AWS Amplify CLI! We will be using NPM and install to globally on your system, don't forget to add sudo otherwise you will experience permissions error.

$ npm install -g @aws-amplify/cli

with sudo,

$ sudo npm install -g @aws-amplify/cli

Just to make everything clear, just in case.

Once you are done installing aws-amplify globally on your machine, let's then proceed to setting up configuration details so you can integrate this with-in your AWS account as it will ask you to sign in to AWS Console.

Further steps should be continued from the official docs as they provide you the complete steps in setting up your account.

Installing Nuxt

Open up your terminal and navigate into your projects directory or any directory that you prefer to install the Nuxt app. For me I prefer it to be placed under "tutorials" directory since I am creating a tutorial on how to setup Nuxt with AWS Amplify.

$ cd ~/tutorials

Then proceed to execute the command to start the installation process.

# Where <project_name> is the name of the Nuxt project
# In this case I will name it as "nuxt-aws-amplify-todo-app"

$ npx create-nuxt-app <project_name>

In selecting the installation options, for the programming language I select TypeScript since it is my preferred choice and my "go-to" language. Package manager would just be NPM. And the UI library I select "Vuetify.js" I prefer this one since it provides a lot of Material design components out of the box, but you can select any UI library whichever you prefer. For the Nuxt modules, these are optional and you can select anything. For now I will select neither of these modules. Just hit ENTER key to continue without selection.

Same applies to Linting tools and Testing framework just nothing.

We will select rendering mode to be a Single Page Application, and deployment target would be Static since we do not need anything server side rendered. And for the development tools, if you select TypeScript you don't have to choose jsconfig.json otherwise you can. For the other options I will not select any of them for now.

Now to sum it all up regarding our installation selection, this is what we have.

Proceed to opening the new generated Nuxt project in your IDE (Visual Studio Code), do it via

$ cd nuxt-aws-amplify-todo-app && code .

This will then open up Visual Studio Code.

(Optional) Installing Nuxt Dependencies

These are optional but you can follow as well. I will be installing the following:

@nuxtjs/composition-api: This module is not recommended for production but soon it will be once Nuxt 3 comes out. When you are using this package, there will be bugs so keep that in mind in case you might get stuck then you can create an issue from the repository on Github and that counts as your contribution to the package.

Note: I will not cover how to setup this module but you can refer on the official docs instead.

@nuxtjs/google-fonts: I want to use "Sora" font just because FeedHive was using this and I think it's a cool font.

Note: I will not cover how to setup this module but you can refer on the official docs instead.

We'll also want to customize some of the default SCSS variables for Vuetify.js on some components and to apply "Sora" font-family as the main font to be used globally.

To customize, head on over to nuxt.config.js and on to the vuetify property, just add treeShake property with value of true, make sure to have treeShake set to true otherwise overriding SCSS variables for Vuetify will not work.

Also to verify you can reference on the code below on how I setup my nuxt.config.js file for these changes.

export default {
   // ... other properties
   buildModules: [
      // ... 

      '@nuxtjs/composition-api',
      '@nuxtjs/google-fonts'
   ],

   vuetify: {
      customVariables: ["~/assets/variables.scss"],
      treeShake: true
   },

   googleFonts: {
      families: {
         Sora: true
      }
   }
}

Then edit the variables.scss file and setup the following SCSS variables.

$body-font-family: "Sora", sans-serif;
$btn-letter-spacing: 0px !default;
$btn-text-transform: none;

And that's all we have for customizing the look for our Todo application we can then proceed with integrating AWS Amplify into our project.

Integrating AWS Amplify in the Nuxt project

Before we start, install the library so we'll have access to its core.

$ npm i aws-amplify

Now let us setup our backend using AWS Amplify. Given that you already have opened your Nuxt project right after installation then proceed to opening a new terminal instance under your IDE (Visual Studio Code) or if you prefer it in a different window that's fine as well but be sure you are in the root directory of your project.

Then execute this command to initialize or create a new AWS Amplify project.

$ amplify init

When presented with the questions, I have selected the default settings and modified only the "Source Directory Path" to . and for the "Build Command" is set to npm run build && npm run generate since we are going for a Nuxt Static SPA, and lastly the "Start Command" which is npm run start. I believe these build and start commands will be used if you prefer to host it on AWS ecosystem (S3 Bucket)

Once the initialization process is done, it should look similar to this by now.

Next and very important step, you must setup the aws-exports.js plugin. Create a file under plugins directory and name it as aws-amplify.js then copy the following code and paste on to it

import Amplify from "aws-amplify";
import aws_exports from "~/aws-exports";

Amplify.configure(aws_exports);

Then go to nuxt.config.js and add the following into the plugins array

export default {
   // ...

   plugins: ["~/plugins/aws-amplify"]
}

Since we are building a Todo app, then we will need a place to store our data. AWS Amplify can provide us a data store using DynamoDB. So let us continue setting up and add a backend API with the following command.

$ amplify add api

You can follow with my selection:

AWS Amplify already have an existing example for a Todo App so we'll use that one.

And once everything is set up correctly and is done, there are files generated for you with the GraphQL schema, resolvers, all those good stuff. So your project folder would look something like this by now.

Don't worry about the other files the were generated, you don't have to bother with them those are just the configurations files so that AWS Amplify will understand which server instance we are talking to behind the scenes. At least that's how I understand it.

We can take a look at our GraphQL schema that was auto generated by AWS Amplify for us.

Then let us proceed to deploying these into AWS. Let us execute the following command below so we can start making requests to the server via GraphQL.

$ amplify push

You will be then asked some questions to select from by the CLI.

To break it down for you, we tell CLI we want to auto generate GraphQL code, we select TypeScript as the output of the generated code, the filename pattern will reside in a graphql directory, we want AWS Amplify CLI to auto generate us all the possible operations/queries/resolvers that we might use for our Todo App, and the file name of the generated code will reside under api directory with file name as index.ts

Right after the installation process you will then be presented the GraphQL endpoint and the GraphQL API KEY which I don't want to expose it in here.

Now that it's all set up we can then proceed to building the UI of our app.

User Interface

I am just going to make it simple but of course feel free to build the UI in any form you want. For the UI we will have a form and a list that will list out the todos. Before we start building out the UI, open a server for the Nuxt app. In your terminal execute the command.

npm run serve

That will then provide you a URL for the app, typically it is http://localhost:3000 so open it up in your browser.

Once that is done, I made some modifications the following are:

I have deleted two files under components directory those are Logo.vue and VuetifyLogo.vue
I have deleted all the code for the app layout which can be found under layouts directory with file name of default.vue.

<template>
    <v-app app>
       <Nuxt />
    </v-app>
</template>

I have also deleted inspire.vue under pages directory.
And removed all code for index.vue under pages directory and replaced it with the following:

<template>
  <div></div>
</template>

<script lang="ts">
import { defineComponent } from "@vue/composition-api";

export default defineComponent({
  setup() {}
});
</script>

It will be a grid layout, on the left side will be the form and on the right side will be the list.

<template>
  <div>
    <v-row>
      <v-col cols="12" xs="12" sm="12" md="4" lg="4" xl="4">
        <v-form></v-form>
      </v-col>
      <v-col cols="12" xs="12" sm="12" md="8" lg="8" xl="8">
        <v-list>
          <v-list-item></v-list-item>
        </v-list>
      </v-col>
    </v-row>
  </div>
</template>

Creating a Todo

Then we proceed to writing out the code to create our first Todo! Take a look at the code under.

HTML template,

<template>
  <div>
    <v-row>
      <v-col cols="12" xs="12" sm="12" md="6" lg="6" xl="6">
        <v-form ref="formRef" @submit.prevent="submit">
          <v-text-field
            label="Name"
            v-model="formData.name"
            :rules="requiredRule"
          ></v-text-field>
          <v-textarea
            label="Description"
            v-model="formData.description"
          ></v-textarea>
          <v-btn color="primary" class="my-5" large depressed type="submit">
            Submit
          </v-btn>
        </v-form>
      </v-col>
      <v-col cols="12" xs="12" sm="12" md="6" lg="6" xl="6">
        <v-list>
          <v-list-item v-for="(item, index) in todos" :key="index">
            <v-list-item-content>
              <v-list-item-title>{{ index }}</v-list-item-title>
              <v-list-item-subtitle>Description</v-list-item-subtitle>
            </v-list-item-content>
            <v-list-item-action>
              <v-btn color="transparent" depressed fab>
                <v-icon>mdi-delete-outline</v-icon>
              </v-btn>
            </v-list-item-action>
          </v-list-item>
        </v-list>
      </v-col>
    </v-row>
  </div>
</template>

TypeScript code,

import { defineComponent, computed, ref } from "@vue/composition-api";
import { createTodo } from "~/graphql/mutations";
import { API } from "aws-amplify";

type Todo = {
  name: string;
  description?: string;
};

const createTodoDtoDefaults: Todo = Object.freeze({
  name: "",
  description: ""
});

export default defineComponent({
  setup() {
    const formData = ref<Todo>({
      ...createTodoDtoDefaults
    });
    const todos = ref<Todo[]>([]);

    const formRef = ref();

    const requiredRule = computed(() => [
      (v: string) => !!v || "This field is required"
    ]);

    async function submit() {
      if (formRef.value.validate()) {
        await API.graphql({
          query: createTodo,
          variables: {
            input: formData.value
          }
        });

        // reset the `formData` values
        formData.value = {
          ...createTodoDtoDefaults
        };
      }
    }

    return {
      todos,
      formData,
      formRef,
      submit,
      requiredRule
    };
  }
});

By now we already have our form setup and it is using validation from one of the built-in feature of Vuetify's VForm component which is pretty convenient. A user can write a Todo now by typing in to the form, but whenever a user clicks the Submit button when the title field is empty, then it should not continue and therefore the app will not dispatch a call to the GraphQL API to create a new todo. Otherwise the Todo will be created!

Currently this is how the app looks from my end,

Fetching all Todo

When you tried to create a Todo by now, and sure there wasn't any data returned yet. So let us proceed to fetching all Todos from the API.

export default defineComponent({
  setup() {
    // ...

    const todos = ref<Todo[]>([]);

    // ...

    async function fetchAllTodo() {
      const response = await API.graphql({
        query: listTodos
      });
      // @ts-ignore
      todos.value = response.data.listTodos.items as Todo[];
    }

    async function submit() {
      if (formRef.value.validate()) {
        await API.graphql({
          query: createTodo,
          variables: {
            input: formData.value
          }
        });

        // reset the `formData` values
        formData.value = {
          ...createTodoDtoDefaults
        };
        fetchAllTodo();
      }
    }

    onMounted(() => {
      fetchAllTodo();
    });

    // ...
  }
});

So we defined fetchAllTodo() method that handles to fetch all Todos from the API by making a request to GraphQL using the query that was auto-generated for us! We will call this method in two places, under submit() method is when user's form input is valid and a Todo will be created then we should re-fetch the data to show the created Todo on the list. And the other place is from the onMounted life cycle, we are using composition functions so we call it from onMounted(() => {}) as that will handle calling to the API for fetching the Todos that are stored every time a User opens the app the first time.

So for the last time, this is the entire code for this Todo App.

<template>
  <div>
    <v-row>
      <v-col cols="12" xs="12" sm="12" md="6" lg="6" xl="6">
        <v-form ref="formRef" @submit.prevent="submit">
          <v-text-field
            label="Name"
            v-model="formData.name"
            :rules="requiredRule"
          ></v-text-field>
          <v-textarea
            label="Description"
            v-model="formData.description"
          ></v-textarea>
          <v-btn color="primary" class="my-5" large depressed type="submit">
            Submit
          </v-btn>
        </v-form>
      </v-col>
      <v-col cols="12" xs="12" sm="12" md="6" lg="6" xl="6">
        <v-list>
          <v-list-item v-for="(item, index) in todos" :key="index">
            <v-list-item-content>
              <v-list-item-title>{{ item.name }}</v-list-item-title>
              <v-list-item-subtitle>
                {{ item.description }}
              </v-list-item-subtitle>
            </v-list-item-content>
          </v-list-item>
        </v-list>
      </v-col>
    </v-row>
  </div>
</template>

<script lang="ts">
import {
  defineComponent,
  computed,
  ref,
  onMounted
} from "@vue/composition-api";
import { createTodo } from "~/graphql/mutations";
import { API } from "aws-amplify";
import { listTodos } from "~/graphql/queries";

type Todo = {
  name: string;
  description?: string;
};

const createTodoDtoDefaults: Todo = Object.freeze({
  name: "",
  description: ""
});

export default defineComponent({
  setup() {
    const formData = ref<Todo>({
      ...createTodoDtoDefaults
    });
    const todos = ref<Todo[]>([]);

    const formRef = ref();

    const requiredRule = computed(() => [
      (v: string) => !!v || "This field is required"
    ]);

    async function fetchAllTodo() {
      const response = await API.graphql({
        query: listTodos
      });
      // @ts-ignore
      todos.value = response.data.listTodos.items as Todo[];
    }

    async function submit() {
      if (formRef.value.validate()) {
        await API.graphql({
          query: createTodo,
          variables: {
            input: formData.value
          }
        });

        // reset the `formData` values
        formData.value = {
          ...createTodoDtoDefaults
        };
        fetchAllTodo();
      }
    }

    onMounted(() => {
      fetchAllTodo();
    });

    return {
      todos,
      formData,
      formRef,
      submit,
      requiredRule
    };
  }
});
</script>

Conclusion

So we learned how to setup AWS Amplify for our Nuxt app with Composition API and TypeScript. If you have been planning to use AWS Amplify with Nuxt, then I hope this tutorial was helpful for you. However I might have only covered fetching and creating a Todo but as you see it the article has been very long, so I chose not to include those functionalities but you can explore more about AWS Amplify from the official documentation.

Thank you for taking the time to read and if you liked this be sure to like the post as well and if ever you want any future Nuxt tutorials like this let me know!

Full source code can be found from the repository for your reference

Firebase Cloud Functions with firebase-backend package by FilledStacks

Carlo Miguel Dy — Sun, 28 Mar 2021 02:46:22 +0000

Introduction

In this article, we will learn about how to use firebase-backend package by FilledStacks. Why does this package exist and why should we use it? Let's think of a scenario where your app will have a lot of cloud functions, you can export these into their own separate files but it might be challenging or you might have to structure it in a certain way it is maintainable and easier for you. Firebase Backend package handles this for you but we have to follow certain conventions otherwise during build your defined function wouldn't be recognized and will not be deployed, this means Firebase Backend is opinionated in my opinion.

There is a video tutorial for this package which Dane Mackier explains from Fireship's YouTube channel, so in case you haven't seen the video yet here is the link for you to watch

https://www.youtube.com/watch?v=W_VV2Fx32_Y

Also be sure to subscribe to Fireship and FilledStacks channel, they both produce quality content for Firebase and Flutter!

Otherwise if you prefer learning it here, continue to read!

Installation

Suppose you already have a Firebase project created from the console and in your code base as well, but make sure you enable Firebase Blaze plan to enable Cloud Functions. Now let's get right to it:

While you are in your root directory, install the package via NPM

$ npm install firebase-backend

Once that is done we can then proceed to setup index.ts or index.js file. But in this article I will choose TypeScript so we will be setting up firebase-backend package on index.ts

import { FunctionParser } from "firebase-backend";
import * as admin from "firebase-admin";

admin.initializeApp();

exports = new FunctionParser(__dirname, exports).exports;

Here we import FunctionParser from firebase-backend and we also import firebase-admin suppose that we will use Firestore with Admin SDK. This is the only place we initialize admin by admin.initializeApp()

Then we set the exports with the returned value from the FunctionPaser exports

File Structure

When using this package, your file structure would be in a feature based structure and have two sub-directories to distinguish whether it is a REST endpoint or a cloud function that is event driven based on Firestore queries (onCreate, onDelete, onUpdate, onWrite)

src/
 - orders
   - reactive
     - onOrderCreated.function.ts
   - restful
     - confirmOrder.endpoint.ts
index.ts

orders is a feature folder then it contains reactive sub directory and restful sub directory. Where reactive are the ones that are event driven and listens to any changes from Firestore queries and the restful sub directory is our REST endpoints and can be accessible with any specified HTTP methods (GET, POST, PUT, DELETE, etc)

As you may have noticed under reactive folder we name the file as onOrderCreated.function.ts where onOrderCreated is the cloud function name and function will tell the FunctionParser that this is a cloud function, in its code we will also call it onOrderCreated

onOrderCreated.function.ts

import * as functions from "firebase-functions";

exports.onOrderCreated = functions.firestore
  .document('orders/{orderId}')
  .onCreate((snapshot, context) => {
     // code
  })

alternative way of doing it is,

import * as functions from "firebase-functions";

export const onOrderCreated  = functions.firestore
  .document('orders/{orderId}')
  .onCreate((snapshot, context) => {
     // code
  })

confirmOrder.endpoint.ts

And now for creating the REST endpoint we import Endpoint from firebase-backend and the enum RequestType as well to tell what HTTP method should be used to access this endpoint

import { Request, Response } from "express";
import { RequestType, Endpoint } from "firebase-backend";

export default new Endpoint(
  "confirmOrder/:id",
  RequestType.PATCH,
  (request: Request, response: Response) => {
  const params = request.params

  response.status(200).json({ message: `Order confirmed for ID ${params.id}` })
})

And that's how we define our cloud functions and a REST endpoint

Building and deployment

Before anything else, we must install rimraf and make a little bit of configuration on or package.json file

Now install rimraf as a dev dependency via

npm i -d rimraf

And let us then modify our package.json under scripts

"scripts": {
    ...
    "clean": "rimraf lib/",
    "prebuild": "npm run clean",
  },

Now just add "clean" and "prebuild", where "prebuild" will always get executed every time you execute a build

Once that is done you can start up your emulators and test it out or you can then deploy your cloud function to Firebase servers.

Conclusion

The firebase-backend package definitely helped us to structure a production level code for our Cloud Functions, this means our Cloud Functions is maintainable, readable, and very good for debugging because of how we name things and how firebase-backend encourages us to do that.

This is still a new package by FilledStacks but definitely it is a good one and one I would use for any of my apps that will get built for production.

FilledStacks always impresses me so if you like Flutter be sure to check out https://www.filledstacks.com/

That is all I have and thank you for taking the time to read this article, I appreciate it and I am happy if this was anything that helped you out. Cheers!

Forem: Carlo Miguel Dy

Firebase Cloud Functions Jest Setup with TypeScript & Mocking

Overview

Introduction

Setup Jest TypeScript

Writing our First Unit Test

Writing our First Test with Mocking

Wrapping Up

Unit Testing a Solidity Smart Contract using Chai & Mocha with TypeScript

Overview

The Stack

Installation

Running a Test

Updating the Greeter smart contract

Writing our tests

Writing a test for function sum

Writing a test for getMyLuckyNumber function

Writing tests for saveLuckyNumber function

Writing tests for updateLuckyNumber

Conclusion

Generating Fake Data in Flutter using the Factory Pattern for Unit Testing

Introduction

Packages

Setup

Creating the ModelFactory abstract

Defining our data models

Creating a factory class

Sample usage for generating fake data from the factory class

Conclusion

Laravel Inversion of Control Implementation using Contextual Binding

Introduction

What is Inversion of Control?

When to use Inversion of Control?

Creating a PaymentInterface

Creating payment services that implements PaymentInterface

Exposing the payment service providers to REST API

Contextual Binding

Manually Testing in browser

Conclusion

Data Modeling with Flutter using freezed package

Introduction

Installation

JSONPlaceholder response

Creating a data model without freezed

Creating a data model with freezed

Generating code using build_runner package

Copying values from a data model but only change values of specific properties

Consuming the REST API

Using "copyWith" method from a data model

Example usage for @JsonKey annotation

Finalizing our data models

Conclusion

Building a simple Grocery App in Flutter with Supabase

Introduction

Demo

Database Design

Relationships

Supabase setup

Creating Tables

Flutter Datamodels

Flutter Setup

Supabase Queries

Authentication

Supabase Service

Summary

Building a simple blog site with Next.js + Strapi API

Introduction

File Structure

Installation

Creating a Post Collection

Creating Posts

Allow read access to Public

Testing

Frontend

Creating a PostCard component

Use the PostCard component

Post detail view

Summary

Dependency Injection with Vue 3

Introduction

Example usage for `@JsonKey` annotation