model.constant.ts

Defines the data shape (schema) inside the database. It ensures consistency in the data storage form and defines indexing for queries.
The constant file unifies the data rules of schema - api - fetch by being used by both the backend and frontend.
In the constant, the following data shapes should be defined in order.

Core Functions of Schema Definition

Type	Description	Example
Input	Data required to create a schema	DroneInput
Object	Schema completed when data is created	DroneObject
Light	Lightweight schema and class-based form used when multiple data is queried	LightDrone
Full	Class-based complete form of data	Drone
Insight	Statistical data that can be extracted when data is queried	DroneInsight
Summary	Statistical data extracted periodically when data is monitored	DroneSummary
query	Data that defines the method of querying and the query statement in advance	droneQuery
sort	Sort key-sort value used when data is sorted	droneSort

Input→DroneInput

Data required to create a schema

Object→DroneObject

Schema completed when data is created

Light→LightDrone

Lightweight schema and class-based form used when multiple data is queried

Full→Drone

Class-based complete form of data

Insight→DroneInsight

Statistical data that can be extracted when data is queried

Summary→DroneSummary

Statistical data extracted periodically when data is monitored

query→droneQuery

Data that defines the method of querying and the query statement in advance

sort→droneSort

Sort key-sort value used when data is sorted

Importance of Schema Structure

These data shapes are used to create the domain and the overall schema shape. Finally, it reflects the data shape of mongoDB schema, statistics model, GraphQL, and RestAPI, and defines the find and sort form when performing a query, allowing you to design the entire schema structure in a single file.

1. Model.Input

Overview

Defines the shape required for data creation in the decorated class form.

As shown in the example below, if you create a domain called drone and need name and websocket URI to create drone data, it can be declared as follows.

1
2@Model.Input('DroneInput')
3export class DroneInput {
4  @Field.Prop(() => String) // String, Int, Boolean, Float, JSON...
5  name: string;
6
7  @Field.Prop(() => String, { default: 'ws://10.10.150.10:9091' })
8  wsUri: string;
9}

Usage Case

Fields declared as above can be used type-safely at the upper level as follows.

Document Creation in drone.document.ts

1new this.Drone({'{ name: "myDrone", wsUri: "ws://10.10.150.10:9091" }'});

Data Creation Logic in drone.service.ts

1this.createDrone({'{ name: "myDrone", wsUri: "ws://10.10.150.10:9091" }'});

Data Creation API Call in drone.store.ts

1fetch.createDrone({'{ name: "myDrone", wsUri: "ws://10.10.150.10:9091" }'});
2fetch.updateDrone("droneId",{'{ name: "myDrone", wsUri: "ws://10.10.150.10:9091" }'});

Usage in Drone.Template.ts & Drone.Util.ts

1
2// Template.ts
3st.do.setNameOnDrone("myDrone"); // set state of form for create or update
4const droneForm = st.use.droneForm(); // droneForm.name
5
6// Util.ts
7const drone = st.use.drone(); // drone.name
8

2. Model.Object

Overview

Defines fields that are automatically created after data is created, and these fields are not modified through Model.Input and create or update.
Enter fields that are modified through separate API and service logic.

For example, status is an object field that is automatically added to all domains as the top-level state of data.

1
2export const droneStatuses = ['active', 'offline', 'inactive'] as const;
3
4export type DroneStatus = (typeof droneStatuses)[number];
5
6@Model.Object('DroneObject')
7export class DroneObject extends BaseModel(DroneInput) {
8  @Field.Prop(() => String, { enum: droneStatuses, default: 'offline' })
9  status: DroneStatus;
10}
11

Usage Case

Fields declared as above can be used type-safely at the upper level as follows.

Document Lookup in drone.document.ts

1const drone = await this.Drone.pickById("droneId"); // drone.status

Data Lookup in drone.service.ts

1const drone = await this.getDrone("droneId"); // drone.status

Data Lookup in drone.store.ts

1const drone = await fetch.drone("droneId"); // drone.status

Data Lookup in Drone.Util.ts

1const drone = st.use.drone(); // drone.status

3. Model.Light

Overview

Light model is a lightweight version of the object by picking field names from the existing object without declaring fields through Field.Prop, and it helps you use data more conveniently by declaring convenience functions.

In addition, it helps you use data more conveniently by declaring convenience functions.

Performance Optimization Benefits

In the case of a list query that fetches multiple data at once, the number of data fields required in the UI is less, and to prevent overfetch, it is declared with light model by selecting only the necessary fields.

1@Model.Light('LightDrone')
2export class LightDrone extends Light(DroneObject, [
3 'name',
4 'status',
5] as const) {
6 isConnected() {
7   return this.status !== 'offline';
8 }
9}

Usage Case

Fields declared as above can be used type-safely at the upper level as follows.

Data Lookup in drone.store.ts

1const droneList = await fetch.droneList({'{ status: "active" }'});
2// drone.name is possible, but drone.wsUri is not possible

Data Lookup in Drone.Util.ts

1const droneMap = st.use.droneMap(); // Map<string, LightDrone>

4. Model.Full

full 모델은 Field.Prop을 통한 필드를 선언하지 않고, 기존의 object에서 편의함수 선언을 통해 도메인 데이터를 손쉽게 사용할 수 있습니다.

1@Model.Full('Drone')
2export class Drone extends Full(DroneObject, LightDrone) {
3  static isDronesAllConnected(droneList: LightDrone[]) {
4    return droneList.every((drone) => drone.isConnected());
5  }
6  isAvailable() {
7    return this.isConnected() && this.wsUri.startsWith("ws://");
8  }
9}

Usage Case

Fields declared as above can be used type-safely at the upper level as follows.

Data Lookup in drone.store.ts

1const drone = await fetch.drone("droneId"); // drone.isAvailable()

Data Lookup in Drone.Util.ts

1const droneMap = st.use.droneMap(); // Map<string, LightDrone>
2const droneList = [...droneMap.values()];
3const isAllConnected = cnst.Drone.isDroneAllConnected(droneList);

5. Model.Insight

Insight model defines a schema that can query the total statistics of documents matching the query when the query is executed.

1
2@Model.Insight('DroneInsight')
3export class DroneInsight {
4 @Field.Prop(() => Int, {"{ default: 0, accumulate: { $sum: 1 } }"})
5 count: number;
6}

Usage Case

Fields declared as above can be used type-safely at the upper level as follows.

Data Lookup in drone.service.ts

1const droneInsight = await this.insight({"{ ...query }"}); // droneInsight.count

Data Lookup in drone.store.ts

1const droneInsight = await fetch.droneInsight({"{ ...query }"}); // droneInsight.count

Data Lookup in Drone.Util.ts

1const drone = st.use.droneInsight(); // droneInsight.count

7. Model.Query

modelQuery is a detailed query statement that defines how to query the completed Full/Light/Insight model.

1export const droneQuery = {"{
2 ...baseQueries,
3 byName: (name: string) => ({"{ name }"}),
4}

Usage Case

Fields declared as above can be used type-safely at the upper level as follows.

Data Lookup in drone.document.ts

1const drone = await this.findByName("myDrone"); // db.Drone | null
2const drone = await this.findIdByName("myDrone"); // string | null
3const drone = await this.pickByName("myDrone"); // db.Drone
4const drone = await this.pickIdByName("myDrone"); // string
5const drones = await this.listByName("myDrone"); // db.Drone[]
6const droneIds = await this.listByName("myDrone"); // string[]
7const droneCount = await this.countByName("myDrone"); // number
8const droneExists = await this.existsByName("myDrone"); // string | null
9const droneInsight = await this.insightByName("myDrone"); // db.DroneInsight

Data Lookup in drone.service.ts

1const drone = await this.findByName("myDrone"); // db.Drone | null
2const drone = await this.findIdByName("myDrone"); // string | null
3const drone = await this.pickByName("myDrone"); // db.Drone
4const drone = await this.pickIdByName("myDrone"); // string
5const drones = await this.listByName("myDrone"); // db.Drone[]
6const droneIds = await this.listByName("myDrone"); // string[]
7const droneCount = await this.countByName("myDrone"); // number
8const droneExists = await this.existsByName("myDrone"); // string | null
9const droneInsight = await this.insightByName("myDrone"); // db.DroneInsight

8. Model.Sort

modelSort is a detailed sort statement that defines how to sort the completed Full/Light/Insight model.

1export const droneSort = {"{
2 ...baseSorts,
3 alphabetical: {"{ name: 1 }"},
4}

Usage Case

Fields declared as above can be used type-safely at the upper level as follows.

Data Lookup in drone.document.ts

1const drone = await this.findByName("myDrone", { sort: "alphabetical" });
2const drone = await this.findIdByName("myDrone", { sort: "alphabetical" });
3const drone = await this.pickByName("myDrone", { sort: "alphabetical" });
4const drone = await this.pickIdByName("myDrone", { sort: "alphabetical" });
5const drones = await this.listByName("myDrone", { sort: "alphabetical" });
6const droneIds = await this.listByName("myDrone", { sort: "alphabetical" });

Data Lookup in drone.service.ts

1const drone = await this.findByName("myDrone", { sort: "alphabetical" });
2const drone = await this.findIdByName("myDrone", { sort: "alphabetical" });
3const drone = await this.pickByName("myDrone", { sort: "alphabetical" });
4const drone = await this.pickIdByName("myDrone", { sort: "alphabetical" });
5const drones = await this.listByName("myDrone", { sort: "alphabetical" });
6const droneIds = await this.listByName("myDrone", { sort: "alphabetical" });

9.1. Advanced - Relation

Designing a schema follows the basic principles of MongoDB schema design.

9.1.1. Scalar Embedded style

If you want to add detailed information without any special scaling or purpose, you can declare a Scalar model and embed the schema as a field.

1@Model.Scalar('DronePhysicalState')
2export class DronePhysicalState {
3 @Field.Prop(() => [Float], { default: [0, 0, 0] })
4 rpy: [number, number, number];
5
6 @Field.Prop(() => [Float], { default: [0, 0, 0] })
7 position: [number, number, number];
8
9 @Field.Prop(() => [Float], { default: [0, 0, 0] })
10 velocity: [number, number, number];
11}

1import { DronePhysicalState } from '../_lfg/lfg.constant';
2
3// ... //
4
5@Model.Object('DroneObject')
6export class DroneObject extends BaseModel(DroneInput) {
7 @Field.Prop(() => DronePhysicalState)
8 physicalState: DronePhysicalState;
9}

9.1.2. Reference ID style

For relationships that require separate collection separation, it is possible to declare fields by referencing ObjectID.

1@Model.Input('MissionInput')
2export class MissionInput {
3 @Field.Prop(() => ID, {"{ ref: 'drone' }"})
4 drone: string;
5}

9.1.3. Resolved Reference style

For relationships that require separate collection separation, it is possible to declare fields by referencing ObjectID.

1import { LightMission } from '../mission/mission.constant';
2
3// ... //
4
5@Model.Object('DroneObject')
6export class DroneObject extends BaseModel(DroneInput) {
7 @Field.Prop(() => LightMission, { nullable: true })
8 mission: LightMission | null;
9}

Constant file imports can cause circular references. It is necessary to design import as a one-way reference structure, and it is not possible to import from index.ts or barrel file.

1import {"{ LightMission }"} from "../cnst_";

Correct Example

1import {"{ LightMission }"} from "../mission/mission.constant";

9.2. Advanced - Field Types

9.2.1. Field.Prop

It is a field that can be used in both backend and frontend as a general schema field declaration.

9.2.2. Field.Hidden

It is a field that can be used freely in the backend, but is restricted in the frontend due to security issues.

9.2.3. Field.Secret

It is a field that is declared when a field that is stored once in the database and has a long query/change cycle or contains sensitive security information is declared. In general, all queries are restricted in the query.

9.2.4. Field.Resolve

It is a field that is used when there is a need to pre-calculate information needed for display on the frontend without being stored in the database.

9.3. Advanced - Field Options

Various options that can be used together with Field.Prop, defining the characteristics and validation of the field.

Option	Type	Default	Description	Example
nullable	boolean	false	Field value required, if nullable: true, data can be saved even if it is not present	`1@Field.Prop(()=> String, { default: "untitled" }) title: string;`
ref	string	-	Option for reference ID field, can specify reference collection name(e.g. drone)	`1@Field.Prop(()=> ID, { ref: "drone" }) drone: string;`
refPath	string	-	Option for reference ID field, if reference collection is variable, can specify reference collection name by referring to other field values	`1@Field.Prop(()=> ID, { refPath: "rootType" }) root: string; @Field.Prop(()=> String, { enum: ["drone", "mission"] }) rootType: string;`
default	any	-	Default value set when no value is entered, must be set for all fields except Model.Input	`1@Field.Prop(()=> String, { default: "untitled" }) title: string;`
type	email \| password \| url	-	Preset setting, default validation or example value is set	`1@Field.Prop(()=> String, { type: "email" }) email: string;`
immutable	boolean	false	Option that cannot be changed after document creation, after creation, changes to the field are not possible	`1@Field.Prop(()=> ID, { immutable: true }) creator: string;`
min	number	-	If the field's model is Int or Float, the minimum value can be limited in the save step	`1@Field.Prop(()=> Int, { min: 0 }) progress: number;`
max	number	-	If the field's model is Int or Float, the maximum value can be limited in the save step	`1@Field.Prop(()=> Float, { min: 0, max: 1 }) ratio: number;`
enum	any[]	-	If the field is enum, the const array can be specified to limit values other than the save step	`1@Field.Prop(()=> String, { enum: ["active", "inactive"] }) status: "active" \| "inactive";`
minlength	number	-	If the field's model is String, the minimum length of the string can be limited	`1@Field.Prop(()=> String, { minlength: 2 }) name: string;`
maxlength	number	-	If the field's model is String, the maximum length of the string can be limited	`1@Field.Prop(()=> String, { maxlength: 30 }) title: string;`
query	object	-	Used in Model.Summary fields, the value obtained by performing the query is saved as the field's value	`1@Field.Prop(() => Int, { min: 0, default: 0, query: { status: { $ne: 'inactive' } } }) totalDrone: number;`
accumulate	object	-	Used in Model.Insight fields, the value calculated in the aggregation step is saved as the field's value	`1@Field.Prop(() => Int, { default: 0, accumulate: { $sum: 1 } }) count: number;`
example	any	-	Can set the value that appears as an example when creating API Docs	`1@Field.Prop(()=> String, { example: "contact@akanjs.com" }) email: string;`
of	any	-	If the field's model is Map, the key value of the Map is string, and the model specified by of is set as the value type of the schema	`1@Field.Prop(()=> Map, { of: Date }) readAts: Map<string, Dayjs>;`
validate	any(value, model) => boolean	-	Can check validation in the save step.(unstable)	`1@Field.Prop(()=> String, { validate: (value)=> value.includes("@") }) email: string;`

nullable:boolean:false

Field value required, if nullable: true, data can be saved even if it is not present

1@Field.Prop(()=> String, { default: "untitled" }) title: string;

ref:string:-

Option for reference ID field, can specify reference collection name(e.g. drone)

1@Field.Prop(()=> ID, { ref: "drone" }) drone: string;

refPath:string:-

Option for reference ID field, if reference collection is variable, can specify reference collection name by referring to other field values

1@Field.Prop(()=> ID, { refPath: "rootType" }) root: string; @Field.Prop(()=> String, { enum: ["drone", "mission"] }) rootType: string;

default:any:-

Default value set when no value is entered, must be set for all fields except Model.Input

1@Field.Prop(()=> String, { default: "untitled" }) title: string;

type:email | password | url:-

Preset setting, default validation or example value is set

1@Field.Prop(()=> String, { type: "email" }) email: string;

immutable:boolean:false

Option that cannot be changed after document creation, after creation, changes to the field are not possible

1@Field.Prop(()=> ID, { immutable: true }) creator: string;

min:number:-

If the field's model is Int or Float, the minimum value can be limited in the save step

1@Field.Prop(()=> Int, { min: 0 }) progress: number;

max:number:-

If the field's model is Int or Float, the maximum value can be limited in the save step

1@Field.Prop(()=> Float, { min: 0, max: 1 }) ratio: number;

enum:any[]:-

If the field is enum, the const array can be specified to limit values other than the save step

1@Field.Prop(()=> String, { enum: ["active", "inactive"] }) status: "active" | "inactive";

minlength:number:-

If the field's model is String, the minimum length of the string can be limited

1@Field.Prop(()=> String, { minlength: 2 }) name: string;

maxlength:number:-

If the field's model is String, the maximum length of the string can be limited

1@Field.Prop(()=> String, { maxlength: 30 }) title: string;

query:object:-

Used in Model.Summary fields, the value obtained by performing the query is saved as the field's value

1@Field.Prop(() => Int, { min: 0, default: 0, query: { status: { $ne: 'inactive' } } }) totalDrone: number;

accumulate:object:-

Used in Model.Insight fields, the value calculated in the aggregation step is saved as the field's value

1@Field.Prop(() => Int, { default: 0, accumulate: { $sum: 1 } }) count: number;

example:any:-

Can set the value that appears as an example when creating API Docs

1@Field.Prop(()=> String, { example: "contact@akanjs.com" }) email: string;

of:any:-

If the field's model is Map, the key value of the Map is string, and the model specified by of is set as the value type of the schema

1@Field.Prop(()=> Map, { of: Date }) readAts: Map<string, Dayjs>;

validate:any(value, model) => boolean:-

Can check validation in the save step.(unstable)

1@Field.Prop(()=> String, { validate: (value)=> value.includes("@") }) email: string;

Quick Start

Released under the MIT License

Official Akan.js Consulting onAkansoft

System managed bybassman