@five12days/core NPM

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 bash 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"
```