FTD Core

Core Package to help Generate Code fot FTD Application Development framework. This will use a defined schema to generate core functionality

Features

• Generate base code using a defined schema
• Follows clean architecture patterns to maximize portability
• Users will only need to maintain essential code (Business logic) in their repository as the rest will be generated by this tool

Getting Started

• First install the dev dependancy dotenv using the following command.

      npm install -D dotenv

• Run the following code to install and initiate the FTDCore package in your local project.

      npx @five12days/core --init

• Or you can manually setup FTDCore by using the following steps.
  • Run

      npm install @five12days/core

• Add the following text to the scripts in package.json.

      "ftd:init" : "frd-core -init"
      "ftd:gen" : "ftd-core -gen"
      "ftd:deploy" : "ftd-core -deploy"

• Run

      npm run ftd:init

• Update the .gitignore files with the following line.

  *.gen.ts

• Define the schema files according to the definitions
• You can generate the SQL table definitions and deploy them using the following command

      npm run ftd:deploy

• Once the definitions are done run the following command

      npm run ftd:gen

• To enable schema parsing in VS code add the following lines to in the json:schema section of the settings page and make sure that json schema download is enabled

    {
      "fileMatch": ["/*.ftd.json"],
      "url": "https://five12daysgeneral.s3.ap-southeast-1.amazonaws.com/ftd-core/ftdModel.schema.json"
    },
    {
      "fileMatch": ["ftd_config.json"],
    	    "url": "https://five12daysgeneral.s3.ap-southeast-1.amazonaws.com/ftd-core/ftdConfig.schema.json"
    }

Schema definition

A basic modle definitions should end with .ftd.json. You can see a sample below

  {
      "name": "CustomerOrder",
      "attributes": {
          "OrderNo": { "type": "Number", "flags": "KMI-" },
          "TotalAmount": { "type": "Decimal", "flags": "AMIU" },
          "Date": { "type": "Timestamp", "flags": "A-I-" }
      }
  }

• Name is the name of the entity (Table)
• Attributes contain the properties of the entity (Columns)
• Valid attribute types are
  • Number (Int)
  • BigNumber(BigInt)
  • Decimal (Decimal(12,2))
  • Float (Float)
  • Date (Date)
  • Timestamp (Timestamp) -- Use when timezone is needed
  • String (Varchar) -- Define a max length when using
• Attribute flags
  • K Primary attribute (Primary Key)
  • A Normal attribute
  • M Mandatory field
  • I Insetable field
  • U Updatable field
• Attribute flag should be <Primary/Normal flag><Mandatory flag><Insertable flag><Updatable flag> i.e KMI-

Usage

• When a schema is defined you can generate the code for it using sh npm run ftd:gen this will create three files for a schema.
  • .gen.ts (located at ./gen/) - contains the zod definition and the the createModel method
  • BaseUseCases.gen.ts (located at ./gen/) - contains the CRUD base use cases that contains the basic validations that are defined in the schema
  • UseCases.ts (located at ./useCases/) - contains the CRUD use cases that can be used to costomize crud logic as needed
• Note that all files in the gen folder will not be required to be commited to your repo and will be generated everytime you run ftd:gen
• To execute uses cases as transactions (To execute multiple sql transactions atomically) you have to wrap your use cases in an executeTransaction method. You can see examples of these in the generated useCases file. Please check the methods that does not end with '_' as you can see methods that ends like that contains the implementation details and the methods that do not have it adds the transaction wrapper to it.
• Whenever you create custom usecases make sure to include 'executeQuery' parameter as a part of its parameter list you can use this to execute your sql.

Deployment

• When you are ready to make a production build make sure to change the build script in your package.json so that it starts with ftd-core -gen && this will make sure that all files that needs to be generated are generated before doing the build. As an example, if you have simple typescript project the build script should look like the following.

  "build": "ftd-core -gen && tsc"

Limitations

• As of now we can only use mysql databases with this solution