Besmellah Allah Alrahman Alrahim

Introduction

Lesan is a collection of a Web Server and an ODM along with an idea to implement microservices.

In this framework, we tried to delegate data retrieval management to the client, inspired by the idea of GraphQL, without adding an extra layer (such as GQL language processors) on the client and server side. In addition, we use all the capabilities of NoSQL databases so that we can embed all the relationships of a schema within itself without involving the server-side programmer in managing the creation, retrieval, updating, and deletion of duplicated embeddings.

Meanwhile, we should have a regular structure (such as SQL) for data models in the ODM layer so that we can always validate the data.

Also, we have provided a new definition for creating relationships between data, which makes us fully master its details and do wonderful things with them. Read more aboit it here

Furthermore, we tried to provide the possibility of being movable for the data structure along with the functions written on the server side so that we can manage microservices more easily.

Finally, this data structure (by the favor of fewer requests sent to the database) will also simplify the way SSG content is created.

In one sentence, Lesan may add a few to five hundred milliseconds to the creation, update, and deletion process, but it makes reading data fifteen to several hundred times faster.

Benchmarks

Lesan

0.130s

Prisma Postgres

1.649s

Prisma Postgres GraphQL

1.973s

Mongoose Not Sort

5.896s

Mongoose Sort

94.106s

We use this formula to calculate the difference : (B - A) ÷ A * 100
As you see on the chart:

Lesan returns data to client 1168% faster than the prisma-express-rest. Which uses postgres as a database.
Lesan returns data to client 1417% faster than the prisma-express-graphql. Which uses postgres as a database.
Lesan returns data to client 4435% faster than the mongoose-express-rest (Note that we did not sort in this query)
Lesan returns data to client 72289% faster than the mongo-express-rest (Note that we did not sort in this query)
Lesan returns data to client 298971% faster than the mongoose-express-rest (used sortby)

Maybe we created the most performant framework in the world! see more detailed benchmark

This video is an introductory tutorial on Lesan framework in Farsi language

Installation

Currently, only the Deno version of Lesan's framework is ready and usable, Node and Bun versions will also be ready soon.

Pre request

At least version 7 of MongoDB must be installed.
The latest version of Deno must be installed.
It is good to have NodeJS installed on your system.
If you need to see database information, it is better to install MongoDB Compass.
Using a suitable editor such as:
- VS Code please install deno extension
- Lesvim The configuration of this editor is a bit difficult.
- Helix The configuration of this editor is simple and the performance is excellent. Please add .helix/languages.toml file to the root of project and insert this config for better support of Deno.

Importing

After completing the prerequisites, create a file named mod.ts. Now just use the latest version of Lesan along with MongoClient in this file.

import {
  lesan,
  MongoClient,
} from "https://deno.land/x/lesan@vx.x.x/mod.ts"; // Please replace `x.x.x` with the latest version in [releases](https://github.com/MiaadTeam/lesan/releases)

const coreApp = lesan();

const client = await new MongoClient("mongodb://127.0.0.1:27017/").connect();

const db = client.db("dbName"); // change dbName to the appropriate name for your project.

coreApp.odm.setDb(db);

coreApp.runServer({ port: 1366, typeGeneration: false, playground: true });

Please replace x.x.x in the import link with the latest version in releases

Now run this command in the terminal:

deno run -A mod.ts

You should see this messsage:

HTTP webserver running.
please send a post request to http://localhost:1366/lesan
you can visit playground on http://localhost:1366/playground

Listening on http://localhost:1366/

Now you can visit the playground at http://localhost:1366/playground. Screen Shot 1402-07-27 at 13 12 58

Because no database model and no function have been written yet, we still cannot send a request to the server.

implement first model

Getting started

I copy this simple example from installation page. We will keep this file as mod.ts and continue to add various models and functions to it.

import { lesan, MongoClient } from "https://deno.land/x/lesan@vx.x.x/mod.ts"; // Please replace `x.x.x` with the latest version in [releases](https://github.com/MiaadTeam/lesan/releases)

const coreApp = lesan();

const client = await new MongoClient("mongodb://127.0.0.1:27017/").connect();

const db = client.db("dbName"); // change dbName to the appropriate name for your project.

coreApp.odm.setDb(db);

coreApp.runServer({ port: 1366, typeGeneration: false, playground: true });

Please replace x.x.x in the import link with the latest version in releases

Add New Model

For adding a new model we should call newModel function from coreApp.odm. Lets add a country model, please add the following code before coreApp.runServer:

const countryPure = {
  name: string(),
  population: number(),
  abb: string(),
};

const countryRelations = {};

const countries = coreApp.odm.newModel(
  "country",
  countryPure,
  countryRelations
);

We also need to import string and number from lesan. These are validators exported from Superstruct. We use Superstruct to define models and validate function inputs and some other things.

The newModel function accepts three inputs:

The first input is to define the name of the new model.
The second input is to define the pure fields of that model in the database. For this, we use an object whose keys are the names of each of the fields, and the value of these keys is obtained by one of the functions exported from Superstruct.
The third input is to define the relationship between models. Because we have just one model here, we pass an empty object for that. We will read more about this later.

Finally, the newModel function returns an object that has services such as insertOne, insertMany, updateOne, deleteOne, and so on.

Add an access point

Every model needs at least one act as an access point to communicate and send or receive data. For adding an act to countries please add the following code before coreApp.runServer:

const addCountryValidator = () => {
  return object({
    set: object(countryPure),
    get: coreApp.schemas.selectStruct("country", 1),
  });
};

const addCountry: ActFn = async (body) => {
  const { name, population, abb } = body.details.set;
  return await countries.insertOne({
    doc: {
      name,
      population,
      abb,
    },
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "country",
  actName: "addCountry",
  validator: addCountryValidator(),
  fn: addCountry,
});

We need to import object function ActFn type from lesan

The `setAct` function

As you can see, to add an act to country, we need to use the setAct function in coreApp.acts. This function receives an object as input that has the following keys:

schema is the name of the model to which we want to set an action.
actName is just a simple string to identify the act.
fn is the function we call when a request arrives for it.
validator is a superstruct object which is called before calling the act fn and validating the given data. Validator includes set and get objects.
An optional key named validationRunType that receives the values of assert and create and determines the type of validator run so that we can create data or change previous data during validation. You can read about it here.
There is another optional key called preAct which receives an array of functions. These functions are executed in the order of the array index before the execution of the main endpoint function. With these functions, we can store information in the context and use it in the main function, or not allow the main function to be executed. We mostly use this key for authorization and authentication. You can think of that key as middleware in Express.
Like preAct, there is another optional key called preValidation. which, like preAct, receives an array of functions and executes them in order before executing the validation function.

There is a context inside Lesan, which is available by contextFns.getContextModel() function. And we can share information between the functions of an Act like preAct, preValidation, validator and fn through this context. By default, the body and header of each request are available in this context.

In addition, the fn function receives an input called body, which is the body of the sent request. If we have changed the body in the context. The body entered in fn function will be updated and changed.

The Validator function

In the addCountryValidator function that we wrote for the validator key, we have returned the object function from the Superstruct struct.
This object contains two key:

set: It is an object in which we define the required input information for each function available on the client side. In the desired function, we can get the set object information from this address. body.details.set. Note that this object must be of Superstruct object function type.

get: This key is also a Superstruct object, where we specify what data can be sent to the client. This object is used in such a way that the client can specify what data he needs with values of 0 or 1 for each key. Actually, this object can be like this:

get: object({
  name: enums([0, 1]),
  population: enums([0, 1]),
  abb: enums([0, 1]),
});

But as you can see, we have used selectStruct function of coreApp.schemas.selectStruct. This function has two inputs. The first input is the name of the model for which we want to generate this object, and the second input specifies the degree of penetration into each relationship. The second input of the selectStruct function can be entered as a number or an object. If entered as an object, the keys of this object must be the names of the selected model relationships, and its value can again be a number or an object of its key relationships. Such as:

  get: coreApp.schemas.selectStruct("country", {
      provinces: {
        cities: 1
      },
      createdBy: 2,
      users:{
        posts: 1
      }
    }),

As a result, an object will be produced as follows:

get: object({
  name: enums([0, 1]),
  population: enums([0, 1]),
  abb: enums([0, 1]),
  provinces: object({
    name: enums([0, 1]),
    population: enums([0, 1]),
    abb: enums([0, 1]),
    cities: object({
      name: enums([0, 1]),
      population: enums([0, 1]),
      abb: enums([0, 1]),
    }),
  }),
  createdBy: object({
    name: enums([0, 1]),
    family: enums([0, 1]),
    email: enums([0, 1]),
    livedCity: object({
      name: enums([0, 1]),
      population: enums([0, 1]),
      abb: enums([0, 1]),
      province: object({
        name: enums([0, 1]),
        population: enums([0, 1]),
        abb: enums([0, 1]),
      }),
    }),
    posts: object({
      title: enums([0, 1]),
      description: enums([0, 1]),
      photo: enums([0, 1]),
      auther: object({
        name: enums([0, 1]),
        family: enums([0, 1]),
        email: enums([0, 1]),
      }),
    }),
  }),
  users: object({
    name: enums([0, 1]),
    family: enums([0, 1]),
    email: enums([0, 1]),
    post: object({
      title: enums([0, 1]),
      description: enums([0, 1]),
      photo: enums([0, 1]),
    }),
  }),
});

We directly send the data received from the get key as a projection to MongoDB.

The `fn` function

The fn key receives the main act function, we write this function for that:

const addCountry: ActFn = async (body) => {
  const { name, population, abb } = body.details.set;
  return await countries.insertOne({
    doc: {
      name,
      population,
      abb,
    },
    projection: body.details.get,
  });
};

This function receives an input called body, the body of the request sent from the client side is passed to it when this function is called, as a result, we have access to the information sent by users. The request body sent from the client side should be a JSON like this:

{
  "service": "main",
  "model": "country",
  "act": "addCountry",
  "details": {
    "set": {
      "name": "Iran",
      "population": 85000000,
      "abb": "IR"
    },
    "get": {
      "_id": 1,
      "name": 1,
      "population": 1,
      "abb": 1
    }
  }
}

The service key is used to select one of the microservices set on the application. You can read more about this here.
The model key is used to select one of the Models added to the application.
The act key is used to select one of the Acts added to the application.
The details key is used to receive data to be sent from the client side along with data to be delivered to users. This key has two internal keys called get and set, we talked a little about it before.
- set: It contains the information we need in the Act function. For this reason, we can extract name, population, and abb from within body.details.set.
- get: Contains selected information that the user needs to be returned. Therefore, we can pass this object directly to Mongo projection.

As you can see, we have used the insertOne function, which was exported from the countries model, to add a new document. This function accepts an object as input, which has the following keys:

{
  doc: OptionalUnlessRequiredId<InferPureFieldsType>;
  relations?: TInsertRelations<TR>;
  options?: InsertOptions;
  projection?: Projection;
}

The doc key receives an object of the pure values of the selected model. OptionalUnlessRequiredId type is the document type in the official MongoDB driver. You can read about it here.
The relations key receives an object from the relations of this model. There is no relationship here. We will read about this in the next section.
The options key gets the official MongoDB driver options to insertOne. You can read more about this here
The projection key is used to receive written data. We use native projection in MangoDB. You can read MongoDB's own documentation here. In insertOne, you can only penetrate one step in relationships. Here you can get only pure fields because there is no relation. We will read more about this later.

The code

So this is all the code we've written so far (You can also see and download this code from here):

import {
  ActFn,
  lesan,
  MongoClient,
  number,
  object,
  string,
} from "https://deno.land/x/lesan@vx.x.x/mod.ts"; // Please replace `x.x.x` with the latest version in [releases](https://github.com/MiaadTeam/lesan/releases)

const coreApp = lesan();

const client = await new MongoClient("mongodb://127.0.0.1:27017/").connect();

const db = client.db("dbName"); // change dbName to the appropriate name for your project.

coreApp.odm.setDb(db);

const countryPure = {
  name: string(),
  population: number(),
  abb: string(),
};

const countryRelations = {};

const countries = coreApp.odm.newModel(
  "country",
  countryPure,
  countryRelations
);

const addCountryValidator = () => {
  return object({
    set: object(countryPure),
    get: coreApp.schemas.selectStruct("country", { users: 1 }),
  });
};

const addCountry: ActFn = async (body) => {
  const { name, population, abb } = body.details.set;
  return await countries.insertOne({
    doc: {
      name,
      population,
      abb,
    },
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "country",
  actName: "addCountry",
  validator: addCountryValidator(),
  fn: addCountry,
});

coreApp.runServer({ port: 1366, typeGeneration: false, playground: true });

Please replace x.x.x in the import link with the latest version in releases

Run Server function

The last thing we want to talk about is the coreApp.runServer function, this function receives an object input that has the following keys:

port used to specify the port used to run the server.
polyground that receives a Boolean value that specifies whether the Polyground is available at http://{server-address}:{port}/playground address.
typeGeneration, which receives a Boolean value and creates a folder named declarations, and inside it, the typefaces of the program are generated to be used in various cases, we will read more about this later.
staticPath that receives an array of paths as a string and makes the content inside these paths statically serveable. We will read more about this later.
cors which receives either the * value or an array of URLs as a string, and makes these addresses have the ability to communicate with the server and not receive the cors error.

Running App

Now you can run deno run -A mod.ts for running the Application with deno

You can use playground: Screen Shot 1402-07-30 at 11 17 19 Or postman: Screen Shot 1402-07-30 at 11 35 40

To send a post request to http://localhost:1366/lesan with this request body:

{
  "service": "main",
  "model": "country",
  "act": "addCountry",
  "details": {
    "set": {
      "name": "Iran",
      "population": 85000000,
      "abb": "IR"
    },
    "get": {
      "_id": 1,
      "name": 1,
      "population": 1,
      "abb": 1
    }
  }
}

For inserting a new country.

You shuold get this result:

{
  "body": {
    "_id": "6534d7c6c5dec0be8e7bf751",
    "name": "Iran",
    "population": 85000000,
    "abb": "IR"
  },
  "success": true
}

Add E2E Test

For adding addCountry request to E2E section you should click on the E2E button, like below picture.

Then, when you go to the E2E section, you can see 2 sequense that first one is the default sequence that you should delete that. so, you have one sequence that include your request information(like bottom picture).

Add relation

As we said before, we embed all relationships. So when you define a relation we store the pure fields of both models in each other.

So far we have defined only one model, let us add the second model.

We add the following code to the previous codes to add a new model called city.

const cityPure = {
  name: string(),
  population: number(),
  abb: string(),
};

const cityRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      cities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
};

const cities = coreApp.odm.newModel("city", cityPure, cityRelations);

We talked about newModel and its input here.

Now we only talk about the third input, the relation definition. which receives an object with string key which is the feild name and we store the relation data by this name inside each document, and TRelation value (relations: Record<string, TRelation>;) which gave us some metadata about the relation. The TRelation type is as follows:

export type RelationDataType = "single" | "multiple";

export type RelationSortOrderType = "asc" | "desc";

export type TRelatedRelation = {
  type: RelationDataType;
  limit?: null | number;
  sort?: {
    field: string;
    order: RelationSortOrderType;
  };
};

interface TRelation {
  schemaName: string;
  type: RelationDataType;
  optional: boolean;
  sort?: {
    field: string;
    order: RelationSortOrderType;
  };
  relatedRelations: {
    [key: string]: TRelatedRelation;
  };
}

The schemaName key receives the exact name of another schema to establish a relation.
The type key specifies whether the relationship type should be single or multiple.
The optional key specifies whether or not it is mandatory to enter information about this relationship when importing a new document.
The sort key is optional and specifies that if the relationship type is multiple, based on which field of the relationship schema, the information should be arranged. This key receives an object with two keys:
- The field that receives the name of one of the schema fields in the relation.
- An order that receives the value of asc and desc and specifies whether the arrangement should be from bottom to top or vice versa.
relatedRelations key that specifies the effects of this schema on the other side of the relationship. This key receives the value of the object with the following keys:
- The type key specifies whether the relationship type should be single or multiple.
- limit which specifies the number of relations to be kept if the relation type is multiple.
- The sort key is optional and specifies that if the relationship type is multiple, based on which field of the relationship schema, the information should be arranged. This key receives an object with two keys:
  - The field that receives the name of one of the schema fields in the relation.
  - An order that receives the value of asc and desc and specifies whether the arrangement should be from bottom to top or vice versa.

Add new `Act` with relation

Let us define an Act for this new model. We add the following code for this purpose:

const addCityValidator = () => {
  return object({
    set: object({
      ...cityPure,
      country: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("city", 1),
  });
};

const addCity: ActFn = async (body) => {
  const { country, name, population, abb } = body.details.set;

  return await cities.insertOne({
    doc: { name, population, abb },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          cities: true,
        },
      },
    },
  });
};

coreApp.acts.setAct({
  schema: "city",
  actName: "addCity",
  validator: addCityValidator(),
  fn: addCity,
});

We need to import objectIdValidation and ObjectId from lesan

We see Validator and Act and setAct and insertOne functions before, Here we are only talking about the relations input in the insert function. The type of this input is as follow:

export type TInsertRelations<T extends IRelationsFileds> = {
  [mainKey in keyof T]?: {
    _ids: ObjectId | ObjectId[];
    relatedRelations?: {
      [key in keyof T[mainKey]["relatedRelations"]]: boolean;
    };
  };
};

This input receives an object with the key name of the relations that we have previously defined in the model. This object has the following keys:

ids which receives either an ObjectId or an array of ObjectIds.
relatedRelations, which receives an object with the key of the name of the related relations that we have previously defined in the model along with a boolean value. If the value is true, in addition to the given relationship being saved in this new document, this created document is also saved in the related relationship. And if it is false, the relationship will be saved only in this new document.

Here, by adding a city and giving the country ID associated with that city, we store both the pure fields of that country in this newly created city, and within that country in an array of objects, we also store the pure fields of this city.

All codes

Let's see all the code written here and run it. (You can also see and download this code from here)

import {
  ActFn,
  lesan,
  MongoClient,
  number,
  object,
  ObjectId,
  objectIdValidation,
  RelationDataType,
  RelationSortOrderType,
  string,
} from "https://deno.land/x/lesan@vx.x.x/mod.ts"; // Please replace `x.x.x` with the latest version in [releases](https://github.com/MiaadTeam/lesan/releases)

const coreApp = lesan();

const client = await new MongoClient("mongodb://127.0.0.1:27017/").connect();

const db = client.db("dbName"); // change dbName to the appropriate name for your project.

coreApp.odm.setDb(db);

const countryCityPure = {
  name: string(),
  population: number(),
  abb: string(),
};

const countryRelations = {};

const countries = coreApp.odm.newModel(
  "country",
  countryCityPure,
  countryRelations
);

const cityRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      cities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
};

const cities = coreApp.odm.newModel("city", countryCityPure, cityRelations);

const addCountryValidator = () => {
  return object({
    set: object(countryCityPure),
    get: coreApp.schemas.selectStruct("country", 1),
  });
};

const addCountry: ActFn = async (body) => {
  const { name, population, abb } = body.details.set;
  return await countries.insertOne({
    doc: {
      name,
      population,
      abb,
    },
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "country",
  actName: "addCountry",
  validator: addCountryValidator(),
  fn: addCountry,
});

const addCityValidator = () => {
  return object({
    set: object({
      ...countryCityPure,
      country: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("city", 1),
  });
};

const addCity: ActFn = async (body) => {
  const { country, name, population, abb } = body.details.set;

  return await cities.insertOne({
    doc: { name, population, abb },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          cities: true,
        },
      },
    },
  });
};

coreApp.acts.setAct({
  schema: "city",
  actName: "addCity",
  validator: addCityValidator(),
  fn: addCity,
});

coreApp.runServer({ port: 1366, typeGeneration: true, playground: true });

Now, by running this code and going to playgroun, you should see this page to add the country: add-country

And to add a new city, you should see this page: add-city

What exactly happened to the database? If you open MongoDB Compass, the following data should be stored for the country: country-data

And the following data should be stored for the city: city-data

As you can see, when you add a city, the pure values are stored as embedded on both sides of the relation. This makes receiving data much faster.
The only noteworthy point is that a limited number of cities are stored in the country. Try to save as many as you think you will need in the first paginate. To get the rest of the cities, we will also query their own schema.

Add E2E Test

Like before, you can click on the E2E button (like bottom picture) to add your request to E2E section.

Then, when you go to the E2E section, you can see 2 sequense that first one is addCountry from getting start page and second one, is addCity request.

In the first sequence, you can click on Add Capture button to show you two input to set variable and value:

Then, you should fill the inputs like bottom picture:

Finaly, In the second sequence, add city, you should delete the country id :

And put the variable name that you set in the capture in the addCountry sequence, in my example, {IranId}.

Add more relation

So far we have created two models and one relationship. Let us create another relationship for these two models.
Just add this object to relatedRelations of city:

citiesByPopulation: {
  type: "multiple" as RelationDataType,
  limit: 50,
  sort: {
    field: "population",
    order: "desc" as RelationSortOrderType,
  },
}

With this relationship, we plan to store the 50 most populated cities of each country in an embedded form.
Now the cityRelations object should look like this:

const cityRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      cities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
      citiesByPopulation: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "population",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
};

And we also need to change the function we wrote to add cities:

const addCity: ActFn = async (body) => {
  const { country, name, population, abb } = body.details.set;

  return await cities.insertOne({
    doc: { name, population, abb },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          cities: true,
          citiesByPopulation: true,
        },
      },
    },
  });
};

We just add this line of code:

  citiesByPopulation: true,

Let us add other relationships before testing this code.

Add arbitrary relation

Let's choose a city as the capital for the countries. For this purpose we must have a single relatedRelation for each country selectively. So we add this code:

capital: {
  type: "single" as RelationDataType,
},

And we change the function and validation we wrote to add the city as follows:

const addCityValidator = () => {
  return object({
    set: object({
      ...countryCityPure,
      country: objectIdValidation,
      isCapital: boolean(),
    }),
    get: coreApp.schemas.selectStruct("city", 1),
  });
};

const addCity: ActFn = async (body) => {
  const { country, name, population, abb, isCapital } = body.details.set;

  return await cities.insertOne({
    doc: { name, population, abb },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          cities: true,
          citiesByPopulation: true,
          capital: isCapital,
        },
      },
    },
  });
};

We just add isCapital: boolean(), to addCityValidator and add capital: isCapital to the insertOne functions.

Run the code

All the code we have written so far is as follows (You can also see and download this code from here):

import {
  ActFn,
  boolean,
  lesan,
  MongoClient,
  number,
  object,
  ObjectId,
  objectIdValidation,
  RelationDataType,
  RelationSortOrderType,
  string,
} from "https://deno.land/x/lesan@vx.x.x/mod.ts"; // Please replace `x.x.x` with the latest version in [releases](https://github.com/MiaadTeam/lesan/releases)

const coreApp = lesan();

const client = await new MongoClient("mongodb://127.0.0.1:27017/").connect();

const db = client.db("dbName"); // change dbName to the appropriate name for your project.

coreApp.odm.setDb(db);

const countryCityPure = {
  name: string(),
  population: number(),
  abb: string(),
};

const countryRelations = {};

const countries = coreApp.odm.newModel(
  "country",
  countryCityPure,
  countryRelations
);

const cityRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      cities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
      citiesByPopulation: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "population",
          order: "desc" as RelationSortOrderType,
        },
      },
      capital: {
        type: "single" as RelationDataType,
      },
    },
  },
};

const cities = coreApp.odm.newModel("city", countryCityPure, cityRelations);

const addCountryValidator = () => {
  return object({
    set: object(countryCityPure),
    get: coreApp.schemas.selectStruct("country", 1),
  });
};

const addCountry: ActFn = async (body) => {
  const { name, population, abb } = body.details.set;
  return await countries.insertOne({
    doc: {
      name,
      population,
      abb,
    },
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "country",
  actName: "addCountry",
  validator: addCountryValidator(),
  fn: addCountry,
});

const addCityValidator = () => {
  return object({
    set: object({
      ...countryCityPure,
      country: objectIdValidation,
      isCapital: boolean(),
    }),
    get: coreApp.schemas.selectStruct("city", 1),
  });
};

const addCity: ActFn = async (body) => {
  const { country, name, population, abb, isCapital } = body.details.set;

  return await cities.insertOne({
    doc: { name, population, abb },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          cities: true,
          citiesByPopulation: true,
          capital: isCapital,
        },
      },
    },
  });
};

coreApp.acts.setAct({
  schema: "city",
  actName: "addCity",
  validator: addCityValidator(),
  fn: addCity,
});

coreApp.runServer({ port: 1366, typeGeneration: true, playground: true });

If you run the code and go to the playground, you will see that a new input called isCapital has been added to add the city, capital-field

and if we put the value true in it, this city will be added to the country as the new capital.

In addition, we have a field called citiesByPopulation in the country, where the 50 most populated cities of the country are stored. population-city

Please note that you only send a request for a new city, and the new city is stored in three different fields with different conditions in the schema of the corresponding country.

Add E2E Test

In following to adding requests to the E2E test section, For adding addCity request to E2E section you should click on the E2E button, like below picture.

Like before, you should change the country id of the addCity request. In the addCity sequence, you should delete the country id :

And put the variable name that you set in the capture in addCountry sequence , in my example, {IranId}.

Add many-to-many relationship

Let us add a new model named user for this purpose. We add the following code for the user model:

const userPure = {
  name: string(),
  age: number(),
};

const users = coreApp.odm.newModel("user", userPure, {
  livedCities: {
    optional: false,
    schemaName: "city",
    type: "multiple",
    sort: {
      field: "_id",
      order: "desc",
    },
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 50,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },

  country: {
    optional: false,
    schemaName: "country",
    type: "single",
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 50,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },
});

Well, in the code above, we have created a new model called user, which has two pure fields with name and age keys. In addition, it has a relationship with the country and the city. Its relationship with the country is single and there is a relatedRelation with the country with a field called users. But its relationship with the city is multiple by the livedCities key, and there is also a relatedRelation with the city with a field called users, which is also multiple. Therefore, the relationship between the city and the user is many-to-many.
The function we want to add a user is as follows:

const addUserValidator = () => {
  return object({
    set: object({
      ...userPure,
      country: objectIdValidation,
      livedCities: array(objectIdValidation),
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const addUser: ActFn = async (body) => {
  const { country, livedCities, name, age } = body.details.set;
  const obIdLivedCities = livedCities.map((lc: string) => new ObjectId(lc));

  return await users.insertOne({
    doc: { name, age },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          users: true,
        },
      },
      livedCities: {
        _ids: obIdLivedCities,
        relatedRelations: {
          users: true,
        },
      },
    },
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "addUser",
  validator: addUserValidator(),
  fn: addUser,
});

We need to import array function from lesan

The only thing worth mentioning in the code above is the livedCities input in validation, which receives an array of IDs as a string. In the Act function, we convert this input into an array of object IDs with a map. Note that the _ids key in the livedCities object receives an array of object IDs.

Well, let's see the complete code again, run the software and check the outputs.

All codes

You can see and download this code from here

import {
  ActFn,
  array,
  boolean,
  lesan,
  MongoClient,
  number,
  object,
  ObjectId,
  objectIdValidation,
  RelationDataType,
  RelationSortOrderType,
  string,
} from "https://deno.land/x/lesan@vx.x.x/mod.ts"; // Please replace `x.x.x` with the latest version in [releases](https://github.com/MiaadTeam/lesan/releases)

const coreApp = lesan();

const client = await new MongoClient("mongodb://127.0.0.1:27017/").connect();

const db = client.db("dbName"); // change dbName to the appropriate name for your project.

coreApp.odm.setDb(db);

const countryCityPure = {
  name: string(),
  population: number(),
  abb: string(),
};

const countryRelations = {};

const countries = coreApp.odm.newModel(
  "country",
  countryCityPure,
  countryRelations
);

const cityRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      cities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
      citiesByPopulation: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "population",
          order: "desc" as RelationSortOrderType,
        },
      },
      capital: {
        type: "single" as RelationDataType,
      },
    },
  },
};

const cities = coreApp.odm.newModel("city", countryCityPure, cityRelations);

const userPure = {
  name: string(),
  age: number(),
};

const users = coreApp.odm.newModel("user", userPure, {
  livedCities: {
    optional: false,
    schemaName: "city",
    type: "multiple",
    sort: {
      field: "_id",
      order: "desc",
    },
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 5,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },

  country: {
    optional: false,
    schemaName: "country",
    type: "single",
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 5,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },
});

const addCountryValidator = () => {
  return object({
    set: object(countryCityPure),
    get: coreApp.schemas.selectStruct("country", 1),
  });
};

const addCountry: ActFn = async (body) => {
  const { name, population, abb } = body.details.set;
  return await countries.insertOne({
    doc: {
      name,
      population,
      abb,
    },
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "country",
  actName: "addCountry",
  validator: addCountryValidator(),
  fn: addCountry,
});

const addCityValidator = () => {
  return object({
    set: object({
      ...countryCityPure,
      country: objectIdValidation,
      isCapital: boolean(),
    }),
    get: coreApp.schemas.selectStruct("city", 1),
  });
};

const addCity: ActFn = async (body) => {
  const { country, name, population, abb, isCapital } = body.details.set;

  return await cities.insertOne({
    doc: { name, population, abb },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          cities: true,
          citiesByPopulation: true,
          capital: isCapital,
        },
      },
    },
  });
};

coreApp.acts.setAct({
  schema: "city",
  actName: "addCity",
  validator: addCityValidator(),
  fn: addCity,
});

const addUserValidator = () => {
  return object({
    set: object({
      ...userPure,
      country: objectIdValidation,
      livedCities: array(objectIdValidation),
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const addUser: ActFn = async (body) => {
  const { country, livedCities, name, age } = body.details.set;
  const obIdLivedCities = livedCities.map((lc: string) => new ObjectId(lc));

  return await users.insertOne({
    doc: { name, age },
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          users: true,
        },
      },
      livedCities: {
        _ids: obIdLivedCities,
        relatedRelations: {
          users: true,
        },
      },
    },
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "addUser",
  validator: addUserValidator(),
  fn: addUser,
});

coreApp.runServer({ port: 1366, typeGeneration: true, playground: true });

Open Playground in the browser and go to addUser function.
add-user

Note that the livedCities field receives an array of IDs, you just need to enter an input like ["65466c407123faa9c1f3c180", "65466c2c7123faa9c1f3c17e"]. playground parses it and converts it into an array suitable for sending.

Add E2E Test

Probably you know what to do! For adding addUser request to E2E section you should click on the E2E button, like below picture.

And like before, you should change the country id and this time, change the city id. Of course that first you should add capture to addCity sequences.

In my example, i add the Hamedan city and Tehran city to my user. so , in the addCity sequence of Hamedan, i click on the Add Capture button and fill the inputs like below picture.

And in the addCity sequence of Tehran, i click on the Add Capture button and fill the inputs like below picture.

Then, in the addUser sequence, you can see the curent country id and also lived cities id like below picture.

Only thing you do is just to replace the country id and lived cities id with country id and cities id that you set in the capture sequences. in my example, country id is {IranId} and also my first city id is {HamedanId} and second one is {TehranId}. like below picture.

And last thing you should done is that add capture to addUser sequence for using in feature. i click on the Add Captue button and fill the inputs like below picture.

Mannage relations

So far we have created 3 models that have different relationships.
Can we update these relationships?
Yes we can, but only with addRelation and removeRelation functions.
We should note that we should never manually update the relationships created by Lesan with the update or updateMany function. Let the management of the relationships be entirely in Lesan's hands, so that it can always keep them updated and correct.
Let's use addRelation.

`addRelation` function

Update Many to Many Relation

Pay attention to the following code:

const addUserLivedCityValidator = () => {
  return object({
    set: object({
      _id: objectIdValidation,
      livedCities: array(objectIdValidation),
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const addUserLivedCity: ActFn = async (body) => {
  const { livedCities, _id } = body.details.set;
  const obIdLivedCities = livedCities.map((lc: string) => new ObjectId(lc));

  return await users.addRelation({
    filters: { _id: new ObjectId(_id) },
    projection: body.details.get,
    relations: {
      livedCities: {
        _ids: obIdLivedCities,
        relatedRelations: {
          users: true,
        },
      },
    },
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "addUserLivedCities",
  validator: addUserLivedCityValidator(),
  fn: addUserLivedCity,
});

In addition to the functions insert, update, delete, find, etc., for each model in the Lesan, there are two other functions in addition to MongoDB functions, named addRelation and removeRelation, which are prepared for managing relationships. In the code above, the addRelation function is used. This function receives an object input with the following keys:

A filter key that receives MongoDB findOne filter and finds only one document to change its relationships.
The relations key receives an object from the relations of this model. We talk about the relation input here
The projection key is used to receive written data. Also we talk about projection key here
And another key called replace, which is not used here, and receives a boolean value of false or true. We will talk about this key in the next step.

In the function above, we add one or more cities to the set of cities where a user has lived. In fact, in the validation function, the user ID is received along with an array of city IDs, and in the Act function, we convert the array of city IDs into an array of object IDs and give it to the addRelation function along with the user ID. As a result, on the user side, one or more cities are added to the livedCities array, and on the city side, this user is added to each of the cities whose IDs have been sent.

Run the code

Since all the code is getting bigger and bigger, we put it on GitHub, you can see and download it here.
By running the codes and going to the playground, you can see and test the functions added to the user.
before execute main → country → addUserLivedCities: Screenshot from 2024-01-07 13-30-44 executing main → country → addUserLivedCities: Screenshot 2024-01-07 at 19-12-39 Lesan Playground after execute main → country → addUserLivedCities: Screenshot from 2024-01-07 19-21-46

Add E2E Test

For adding addUserLivedCities request to E2E test section, you should click on the E2E button, like bottom picture.

Then, you should click on the Add Capture button in the addCity sequence and fill the inputs like below picture. in my example i add Mashhad city.

After that, you should change the default user id add lived cities id with capture that you set in the past. the default id is like below picture.

And replace the capture you set in the past like below picture.

Update One to Many Relation

What if in one of these sides our field is an object instead of an array (In fact, the type of relationship is one-to-many or many-to-one.)? For example, let's change the country on the user side.
Look at code below:

const addUserCountryValidator = () => {
  return object({
    set: object({
      _id: objectIdValidation,
      country: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const addUserCountry: ActFn = async (body) => {
  const { country, _id } = body.details.set;

  return await users.addRelation({
    _id: new ObjectId(_id),
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          users: true,
        },
      },
    },
    replace: true,
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "addUserCountry",
  validator: addUserCountryValidator(),
  fn: addUserCountry,
});

In the code above, we get the ID of a user along with the ID of a country and give it to the addRelation function. Please note that the country is not optional in the user model and is defined with a single type. Therefore, if we change the country of a user, we must first find and delete this user in the country he was in before, then add the new country to the user and the user to the new country. For this reason, we have given the value true to the replace key in the addRelation entry. In this function, if we set replace equal to false or do not enter it, no operation will be performed and we will get an error.

Steps to add a country to a user

The bottom line is a bit complicated but has its own charm.

To change the country in a user, we must do the following steps:

Find the user
Finding the user's old country
Find the user's new country
Checking whether this user was part of the list of users in the old country or not (users may exist in several fields in one country, for example, the list of users who are the oldest or the youngest).
Creating a command to delete the user from the old country (from all the lists in which the user was found).
If this list has a certain limit and we have reached the end of this limit, we need to find the next user to be added to this list. For this purpose, we must do the following steps:
- Find out how to save this list.
- Finding the next 3 users who can be added to this list (because it is possible to find either the same user that we intend to delete from the list, or the end user of this list).
- Creating an command to add these 3 users to the end of this list.
- Creating a command to unify this list.
- Creating a command to delete the current user from this list.
- Creating a sorting command for this list according to the method we mentioned in the initial settings of relationships.
- Creating an command to limit this list to the number that we said in the initial settings of relationships.
Creating an command to add this user to all user lists in the new country. (Here we also have to check if this list has limit or not and if so, this user can be added to this list or not, which we have to do step #6 for each list in the new country).
Execution of all the commands we have created so far.
Execution of the command to insert the new country instead of the old country in this user.

Run the code

Since all the code is getting bigger and bigger, we put it on GitHub, you can see and download it here.
By running the codes and going to the playground, you can see and test the functions added to the user.
before execute main → country → addUserCountry: Screenshot from 2024-01-08 11-44-40 executing main → country → addUserCountry: Screenshot 2024-01-08 at 11-45-55 Lesan Playground before execute main → country → addUserCountry:

Add E2E Test

For adding addUserCountry request to E2E test section, you should click on the E2E button, like bottom picture.

Then, in the E2E section and addUserCountry sequence you should replace the user id and country id that you set capture in own sequence with default user id and country id. default user and country id is like below picture.

The replaced user and country id is like below picture.

`removeRelation` function

Update Many to Many Relation

Pay attention to the following code:

const removeLivedCitiesValidator = () => {
  return object({
    set: object({
      _id: objectIdValidation,
      livedCities: array(objectIdValidation),
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const removeLivedCities: ActFn = async (body) => {
  const { livedCities, _id } = body.details.set;

  const obIdLivedCities = livedCities.map((lc: string) => new ObjectId(lc));

  return await users.removeRelation({
    filters: { _id: new ObjectId(_id) },
    projection: body.details.get,
    relations: {
      livedCities: {
        _ids: obIdLivedCities,
        relatedRelations: {
          users: true,
        },
      },
    },
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "removeLivedCities",
  validator: removeLivedCitiesValidator(),
  fn: removeLivedCities,
});

In the code above, the removeRelation function is used. This function receives an object input with the following keys:

A filter key that receives MongoDB findOne filter and finds only one document to change its relationships.
The relations key receives an object from the relations of this model. We talk about the relation input here
The projection key is used to receive written data. Also we talk about projection key here

In the function above, we remove one or more cities to the set of cities where a user has lived. In fact, in the validation function, the user ID is received along with an array of city IDs, and in the Act function, we convert the array of city IDs into an array of object IDs and give it to the removeRelation function along with the user ID. As a result, on the user side, one or more cities are removed from the livedCities array, and on the city side, this user is removed from each of the cities whose IDs have been sent. (To know the steps to do this and understand how the relatedRelations are managed, please read this section, just note that we do not have a document to add here, and we only do the steps to remove and place the next document in the limited lists.)

Run the code

Since all the code is getting bigger and bigger, we put it on GitHub, you can see and download it here.
By running the codes and going to the playground, you can see and test the functions added to the user.
before execute main → user → removeLivedCities: Screenshot from 2024-01-08 13-48-53 executing main → user → removeLivedCities: Screenshot 2024-01-08 at 14-16-37 Lesan Playground after execute main → user → removeLivedCities: Screenshot from 2024-01-08 14-20-24

Add E2E Test

For adding removeLivedCities request to E2E section you should click on the E2E button, like below picture.

Then, in the E2E section and removeLivedCities sequence, you should replace the user id and cities id that you set capture in own sequence with default user id and cities id. default user id and cities id in livedCities is like below picture.

The replaced user and cities id is like below picture.

Update One to Many Relation

If you have created a single type relationship, and if you set the optional equivalent to false, we can not use removeRelation for that please use the addRelation function to replace it (for example we can not use removeRelation to remove country from a user).
But if you set the optional equal to true, we can use the removeRelation function to erase that relationship along with its relatedrelations.
Let's make an optional one-to-many relationship. We create a new relationship for the user:

  mostLovedCity: {
    optional: true,
    schemaName: "city",
    type: "single",
    relatedRelations: {
      lovedByUser: {
        type: "multiple",
        limit: 3,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },

So the full form of users will be:

const users = coreApp.odm.newModel("user", userPure, {
  livedCities: {
    optional: false,
    schemaName: "city",
    type: "multiple",
    sort: {
      field: "_id",
      order: "desc",
    },
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 5,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },

  mostLovedCity: {
    optional: true,
    schemaName: "city",
    type: "single",
    relatedRelations: {
      lovedByUser: {
        type: "multiple",
        limit: 5,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },

  country: {
    optional: false,
    schemaName: "country",
    type: "single",
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 5,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },
});

In this relationship, we add a city as a mostLovedCity for a user, and on the side of the city we add a field called lovedByUser, where we store the last five users who have chosen it as their mostLovedCity.
To erase the mostLovedCity relationship in a user. We must first create this relationship.
So let's write a function to add this relationship:

const addMostLovedCityValidator = () => {
  return object({
    set: object({
      _id: objectIdValidation,
      lovedCity: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const addMostLovedCity: ActFn = async (body) => {
  const { lovedCity, _id } = body.details.set;

  return await users.addRelation({
    filters: { _id: new ObjectId(_id) },
    projection: body.details.get,
    relations: {
      mostLovedCity: {
        _ids: new ObjectId(lovedCity),
        relatedRelations: {
          lovedByUser: true,
        },
      },
    },
    replace: true,
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "addMostLovedCity",
  validator: addMostLovedCityValidator(),
  fn: addMostLovedCity,
});

In the above function, we get the ID of a user and the ID of a city and store that city as mostLovedCity in the user. Also, on the city side, we add this user to the lovedByUser list.

before execute main → user → addMostLovedCity: Screenshot from 2024-01-08 14-52-30 executing main → user → addMostLovedCity: Screenshot 2024-01-08 at 14-53-23 Lesan Playground after execute main → user → addMostLovedCity:

Add E2E Test

Like before, for adding addMostLovedCity request to E2E test section, you should click on the E2E button, like bottom picture.

Then, in the E2E section and addMostLovedCity sequence, you should replace the user id and city id that you set capture in own sequence with default user id and city id. default user id and city id in addMostLovedCity sequence is like below picture.

The replaced user and city id is like below picture.

Well, finally, let's write the mostLovedCity remove function:

const removeMostLovedCityValidator = () => {
  return object({
    set: object({
      _id: objectIdValidation,
      lovedCity: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const removeMostLovedCity: ActFn = async (body) => {
  const { lovedCity, _id } = body.details.set;

  return await users.removeRelation({
    filters: { _id: new ObjectId(_id) },
    projection: body.details.get,
    relations: {
      mostLovedCity: {
        _ids: new ObjectId(lovedCity),
        relatedRelations: {
          lovedByUser: true,
        },
      },
    },
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "removeMostLovedCity",
  validator: removeMostLovedCityValidator(),
  fn: removeMostLovedCity,
});

In the above function, we get the ID of a user along with the ID of a city, and in that user, we delete the mostLovedCity field if it matches this ID, and on the city side, we remove this user from the lovedByUser list. (To know the steps to do this and understand how the relatedRelations are managed, please read this section, just note that we do not have a document to add here, and we only do the steps to remove and place the next document in the limited lists.)

Run the code

before execute main → user → removeMostLovedCity: Screenshot from 2024-01-08 14-54-32 executing main → user → removeMostLovedCity: Screenshot 2024-01-08 at 15-27-19 Lesan Playground after execute main → user → removeMostLovedCity: Screenshot from 2024-01-08 15-54-33

Add E2E Test

For adding removeMostLovedCity request to E2E section you should click on the E2E button, like below picture.

Then, in the E2E section and removeMostLovedCity sequence, you should replace the user id and city id that you set capture in own sequence with default user id and city id. default user id and city id in removeMostLovedCity sequence is like below picture.

The replaced user and city id is like below picture.

What is the relationship really?

Let's compare a bit, it may be funny, but let's do it.

what are a real relationship between People?

Right relationships are lasting and long -term.
Both parties accept responsibility for relationships and changes.
Changes on one side of the relationship also affect the other side.
The two sides of a relationship live together.
If the relationship leads to the birth of a child, both parties will accept the relationship.
If one party dies, especially if it's a lover, the other party probably won't want to live either.

Now let's look at the relationship features in SQL:

There is no real relationship. The two sides have only one connection.
Relationships are not together. And each lives independently.
Relationships are not deep.
Relationships do not give birth to any children. (In Lesan, you will see that relationships encourage you to create new models)
If we want to delete one side of the relationship, especially if the other side is dependent on this side, we will only receive an error message.
And the most important thing is that it is not clear what kind of effects each relationship we create will have on the other side of the relationship.

What are the relationships in NoSQL?

There is no real relationship. In fact, there is no proper connection between the two sides.
If we consider embeding as a relationship:
- the changes of each party have no effect on the other side and cause many inconsistencies in the data.
- the two sides leave each other after the relationship. Infact, it is not clear what kind of effects each relationship we create will have on the other side of the relationship.
In this type of databases, they prevent the child from being born, and if a child is born, only one side will be informed of it and probably will not take much responsibility for it.
There is no management in deleting information and they are easily deleted by either side of the relationship.

And finally what are the relationships in Lesan:

Relationships are as strong as possible, and are described in detail when creating a model.
Relationships fully contain each other's pure properties within themselves.
If a relationship changes, all related parties will be notified and apply the changes according to a process.
By establishing a relationship and seeing many changes on one side of this relationship, you are encouraged to create new relationships. Don't worry, this issue will not add more complexity to the data model, but it will also make the data more understandable. (Below there is an example to understand this)
Having complete information about relationships, we can prevent the deletion of a document that other documents are dependent on with an error message, and we can recursively delete all dependent documents by setting a small option.
And the most important point is that it is exactly clear what effects each relationship we have created will have on the other side of the relationship.

Example

SQL

So let's go back to our example (countries, cities and users)
If we want to define a relationship between the country, city and user models in SQL, this relationship will be as follows (The code below is written for PostgreSQL):

CREATE TABLE country (
  id serial PRIMARY KEY,
  name VARCHAR ( 50 ) UNIQUE NOT NULL,
  abb VARCHAR ( 50 ) NOT NULL,
  population INT NOT NULL,
);

CREATE TABLE city (
  id serial PRIMARY KEY,
  name VARCHAR ( 50 ) UNIQUE NOT NULL,
  abb VARCHAR ( 50 ) NOT NULL,
  population INT NOT NULL,
  country_id INT NOT NULL,
  FOREIGN KEY (country_id)
    REFERENCES country (country_id),
);

CREATE TABLE user (
  id serial PRIMARY KEY,
  name VARCHAR ( 50 ) UNIQUE NOT NULL,
  age INT NOT NULL,
  country_id INT NOT NULL,
  FOREIGN KEY (country_id)
    REFERENCES country (country_id),
  city_id INT NOT NULL,
  FOREIGN KEY (city_id)
    REFERENCES city_id (city_id),
);

Pay attention that the relationships are separated from each other as much as possible and only one ID is kept on one side. Whenever we need to know the details of the relationship, we have to visit both sides of the relationship.
For example, let's imagine that we want the cities of Iran, we must first find Iran and then filter the city using Iran ID.
Now let's imagine that we want to find the country of Iran along with its 50 most populated cities, we have to find Iran first, then find the cities according to the ID filter of the country of Iran along with the sort based on the city population field and the limit of 50.
Let's run a more complex query. Suppose we want to receive 50 most populous cities from the 50 most populous countries in the world.
Or we want to find the oldest people in the 50 most populous countries in the world.
To get the above cities or users, we have to create and execute much more complex queries that may be time-consuming in some cases, although there are alternative ways such as creating separate tables in SQL for these specific purposes, but these ways also add a lot of complexity to the project.

NoSQL

What if we could do the above with just a simple query? NoSQL is designed for this, let's see how these tables are implemented in NoSQL databases (Here we have used mongoose so that we can have the shape of the schemas):

const CountrySchema = new mongoose.Schema ({
	name: String,
	abb: String,
	population: Number,
});
const Country = mongoose.model("Country", CountrySchema)

const CitySchema = new mongoose.Schema ({
	name: String,
	abb: String,
	population: Number,
	country: {
		type: mongoose.Schema.Types.ObjectId,
		ref: Country
	} 
});
const City = mongoose.model("City", CitySchema)

const UserSchema = new mongoose.Schema ({
	name: String,
	age: Number,
	country: {
		type: mongoose.Schema.Types.ObjectId,
		ref: Country
	},
	city: {
		type: mongoose.Schema.Types.ObjectId,
		ref: City
	} 
});
const User = mongoose.model("User", CitySchema)

The code above is exactly equivalent to the code we wrote for PostgreSQL and creates exactly the same tables in MongoDB. All the issues we described for SQL will be present here as well, but wait, we can add other fields to these tables to simplify the complex queries we talked about above.

We can store its cities inside each country by adding a field called cities. Pay attention to the following code:

const CountrySchema = new mongoose.Schema ({
  name: String,
  abb: String,
  population: Number,
  cities: [{
    name: String,
    abb: String,
    population: Number,
  }]
});

Now we can get a country along with its cities just by sending a single query. For example, we can get the country of Iran along with its cities with just one query from the database. But wait, some new issues have arisen.

How should we save the cities inside the country ?
For this, it is necessary to find the country associated with the city in the function we write to add the city and add this new city to the cities field of that country. This means that when adding a city in the table of cities, we must insert a new record and edit a record in the table of countries.
Can we store all the cities of a country within itself ?
The short answer is no, although it is possible that the number of cities in a country can be stored within the country, but in some situations, the number of documents that we need to store inside another document may be very large, such as the users of a country. So what should we do? Save a limited number of cities, how many? The number that we feel should be requested in the first pagination (for example, 50 numbers). So, in the function we have written to store the city, we must be aware that if the field of cities within the country has stored 50 cities within itself, do not add this new city to this field.
What if a city changes ?
Well, as a rule, we should find the country related to that city and check whether this city is stored in the field of cities of that country or not, if yes, we should correct it.
What if a city is removed ?
We need to find the country associated with the city and if this city is present in the field of cities of that country, we should modify that field as well. How? First, we remove this city from the array of cities, then we check whether this field has reached the limited number that we have previously considered for it, if yes, then this country may have other cities that are not in this field. So we need to find one of them and add it to this field.

All this was added just so that we can have its cities when receiving a country!
Don't worry, it's worth it. Because we usually add cities and countries once, besides, its information does not change much (except for the population, which we will talk about later). And on the other hand, these cities and countries will be received many times.

Now, what if we want to get the 50 most populous countries along with the 50 most populous cities of that country?
We can add a new field to the country. Pay attention to the following code:

const CountrySchema = new mongoose.Schema ({
  name: String,
  abb: String,
  population: Number,
  cities: [{
    name: String,
    abb: String,
    population: Number,
  }],
  mostPopulousCities: [{
    name: String,
    abb: String,
    population: Number,
  }],
});

For mostPopulousCities Field, we should consider all the events that happened above, although with a slight change:

What if a city changes ? We need to find the country associated with the city, then see if this city is stored in the cities and mostPopulousCities fields of this country or not. If it is stored in the cities field, we must do the same steps as above, but if it is stored in the mostPopulousCities field, we must first, see which city field has changed, if the population field has changed, this city may no longer be included in this list and we want to remove it from the list and add another city to this list based on its population, otherwise it is possible This city is not in the mostPopulousCities list at all, but due to the change in the city's population, we want to add it to this list. Note that this city may be added anywhere in this list, and on the other hand, if this list has reached the end of the predetermined capacity, we must remove a city from the end.

Let's look at this issue from the other side of the relationship.
What if we want to access the country related to that city from within the cities?
Well, for this purpose, we can add a field called the country in each city. And instead of storing only the country's ID in it, embed all the country's information in it.

const CitySchema = new mongoose.Schema ({
  name: String,
  abb: String,
  population: Number,
  country: {
    name: String,
    abb: String,
    population: Number,
  } 
});

The good thing here is that this field is no longer an array, it's just an object, so we don't have any of the calculations we had to manage cities in the country. And it is enough to find the country related to the city in the function we wrote to add the cities and put it as the value of the country field in the city.
But the critical issue here is that if the country is updated, we must find all the cities related to that country and update the country stored inside the cities as well. Sometimes this number may be very high, for example, consider the country of China or India and put users instead of the city and imagine that all the people of this country are registered in this software, in this case with every update The country should update at least another billion documents (there are different solutions for this problem in the Lesan, which you will see below). Finally, our mongoose model will probably look like this:

  const CountrySchema = new mongoose.Schema ({
  name: String,
  abb: String,
  population: Number,
  cities: [{
    name: String,
    abb: String,
    population: Number,
  }],
  mostPopulousCities: [{
    name: String,
    abb: String,
    population: Number,
  }],
});
const Country = mongoose.model("country", CitySchema);

const CitySchema = new mongoose.Schema ({
  name: String,
  abb: String,
  population: Number,
  country: {
    name: String,
    abb: String,
    population: Number,
  } 
});

const City = mongoose.model("City", CitySchema)

const UserSchema = new mongoose.Schema ({
	name: String,
	age: Number,
	country: {
		type: mongoose.Schema.Types.ObjectId,
		ref: Country
	},
	city: {
		type: mongoose.Schema.Types.ObjectId,
		ref: City
	} 
});
const User = mongoose.model("User", CitySchema)

Lesan

So, if we want to create the same relationships with ‌Lesan, what should we do? Just enter the code below:

// Country Model
const countryCityPure = {
  name: string(),
  population: number(),
  abb: string(),
};

const countryRelations = {};

const countries = coreApp.odm.newModel(
  "country",
  countryCityPure,
  countryRelations,
);

// City Model
const cityRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      cities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
      mostPopulousCities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "population",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
};

const cities = coreApp.odm.newModel(
  "city",
  countryCityPure,
  cityRelations,
);

// User Model
const userPure = {
  name: string(),
  age: number(),
};

const userRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      users: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
  city: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      users: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
};

const users = coreApp.odm.newModel(
  "user",
  userPure,
  userRelations,
);

In the code above, we have not defined any relationship for the country, but in fact, the country is related to both the city and the user, but this relationship is defined by them because they were the requesters of the relationship.
If you pay attention, we have defined two relatedRelations for the country when defining city relations, which causes two fields called cities and mostPopulousCities to be added to the country schema. For the cities field, we have set the sort on _id and in descending order, and we have limited the capacity of the field to 50 numbers with the limit option, which causes the last 50 cities of each country to be stored in it.
But in the mostPopulousCities field we have once again stored 50 cities in each country, but this time by sorting on the City population field.
The important thing here is that all the things we said we need to do in NoSQL databases using Mongoose are done automatically in Lesan and you don't need any additional code to manage these relationships during insert, update or delete. All work will be done by Lesan.

Test Realation in Lesan

Clone and run E2E

you can clone lesan repo by git clone https://github.com/MiaadTeam/lesan.git command and the go to tests/playground folder and run e2e.ts file by execute this command: deno run -A e2e.ts you should see this output:

HTTP webserver running.
please send a post request to http://localhost:1366/lesan
you can visit playground on http://localhost:1366/playground

Listening on http://localhost:1366/

Visit Playground

Now you can visit the playground at http://localhost:1366/playground and send requests to the server for country, city, and user models: Screenshot 2023-12-31 at 21-35-56 Lesan Playground

and use addCountry, addCountries, updateCountry, getCountries, deleteCountry methods for country models: Screenshot 2023-12-31 at 21-42-37 Lesan Playground

also use addCity, updateCity, addCities, getCities and addCityCountry for city model: Screenshot 2023-12-31 at 22-03-07 Lesan Playground

and also use addUser, addUsers, addUserLivedCities, addUserCountry, addUserCities, addMostLovedCity, removeMostLovedCity, removeLivedCities, updateUser, getUser and getUsers for user model:

Screenshot 2023-12-31 at 22-06-53 Lesan Playground you can find e2e.ts raw file here and see all functions write in it.

Visit Schema and Act

You can see all schema information including pure, mainRelation and relatedRelation inside schema modal box at playground when clicking on Schema button: Screenshot 2023-12-31 at 22-33-26 Lesan Playground

here is the screenshot of schema modal box: Screenshot 2023-12-31 at 22-37-13 Lesan Playground

Also you can see all Act information including service, model, act and its inputs such as set and get inside act modal box at playground when clicking on Act button:
Screenshot 2023-12-31 at 22-38-46 Lesan Playground

here is the screenshot of act modal box: Screenshot 2023-12-31 at 22-43-11 Lesan Playground

We have already prepared several E2E test series for e2e.ts's file, and you can go to E2E modal box by clicking the E2E test button:
Screenshot 2023-12-31 at 22-52-21 Lesan Playground

here you can import E2E test config file by clicking on import button:
Screenshot 2023-12-31 at 22-55-06 Lesan Playground

We have these 3 json files next to the e2e.ts file, all three of which can be used for E2E testing:

Configdata E2E file

In the config.json file, all the functions written in e2e.ts have been tested. In fact, all the important functions, including all the functions of the ODM section in Lesan, have been tested in this file. Let us see all the parts of this E2E test one by one (The point is that in almost all the functions written in ODM, relationships are important and Lesan must manage them.):

create new country with main → country → addCountry:
1. here we used main service and country model and addCountry act.
2. we repeat this section 15 times.
3. we captured countryId from last response of this sections.
4. here we used faker for create name, population and abb for new country.
create multiple country with one request with main → country → addCountries:
1. here we used main service and country model and addCountries act.
2. here we insert an array of country for multiCountries key inside set object.
3. we captured some country ID from request response.
create new city with main → city → addCity:
1. here we used iranId the captured variable we get from request number 2 response.
2. we captured body._id with the haratId from response.
create multiple city with main → city → addCities:
1. here we insert an array of city for multiCities key inside set object.
2. here we used iraqId the captured variable we get from request number 2 response.
create multiple city with main → city → addCities:
1. here we insert an array of city for multiCities key inside set object. We also used faker here.
2. here we used afghanId the captured variable we get from request number 2 response.
change country relation of a city with main → city → addCityCountry:
1. here we used haratId and afghanId captured variables. please check mongodb compass beacuase the both side of relation are changend.
create new city with main → city → addCity:
create new city with main → city → addCity:
1. please note that we set isCapital field to true so the capital field of related country is filled with this city.
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
create new city with main → city → addCity:
just get list of countries with main → country → getCountries:
create new city with main → user → addUser:
1. the country were user lived is Iran.
2. the user lived in two city: Hamedan and Tehran.
create new city with main → user → addUser:
create new city with main → user → addUser:
create new city with main → user → addUser:
create new city with main → user → addUser:
create new city with main → user → addUser:
create new city with main → user → addUser:
create new city with main → user → addUser:
create new city with main → user → addUser:
change country relation of a user with main → user → addUserCountry: 1.we just send a country ID with a user ID and with a simple function all magic happen in both side of relation.
change country relation of a user with main → user → addUserCountry:
add city to livedCities relation of a user with main → user → addUserLivedCities: 1.we just send list of city ID with a user ID and with a simple function all magic happen in both side of relation.
add city to livedCities relation of a user with main → user → addUserLivedCities:
remove city from livedCities relation of a user with main → user → removeLivedCities: 1.we just send list of city ID with a user ID and with a simple function all magic happen in both side of relation.
add a city to mostLovedCity relation of a user with main → user → addMostLovedCity:
add a city to mostLovedCity relation of a user with main → user → addMostLovedCity:
remove a city from mostLovedCity relation of a user with main → user → removeLivedCities:
update a country with main → country → updateCountry:
1. We send the ID of a country along with the rest of the pure fields (pure fields are optional) to it, and in a simple function the following will happen:
  - Update the country itself
  - Updating the country field in all cities related to that country
  - Updating the country field in all users related to that country
The point to be mentioned here is that you should not send another field for updating other than pure fields. Because the relationships must be completely managed by Lesan himself.
update a city with main → city → updateCity:
update a user with main → user → updateUser:

After clicking the run E2E test button, you will go to the test results page. Screenshot 2024-01-06 at 13-34-30 Lesan Playground

If you scroll down a little, you can see the results of each sequence separately: Screenshot 2024-01-06 at 14-13-04 Lesan Playground Screenshot 2024-01-06 at 14-20-03 Lesan Playground

with this button you can change view of panel from body-header & Description to REQUEST & RESULT
show some description about sequence including request number & timing, captured value and so on.
show unparsed header and body you send to the backend.
show the index of each sequence.
show response get back from server.
show parsed request you send to server, including parsed header and body.
pagination for sequence with more than 1 request.

After finished executing all test in configdata.json you have a nice data inserted to sample collection in mongodb. Screenshot from 2024-01-06 15-10-49

You can play with this data in playground and change everything you want. Screenshot 2024-01-06 at 15-08-36 Lesan Playground

fakerTest E2E file

This file is not very important in this section, it is only used to test faker functions in E2E. Screenshot 2024-01-06 at 16-47-45 Lesan Playground

stress E2E file

This file is used to test the insertMany that has a relation with it. Note that a very large number of server-side requests are sent, resulting in the creation of a country with 50,000 cities for that country and 50,000 users for that country.

create a country with main → country → addCountry:
create 50,000 cities with main → city → addCities:
create 50,000 users with main → user → addUsers:

After clicking the run E2E test button, 10001 requests should be sent to the server, and as a result, a country, 50,000 cities, and 50,000 users should be created. Screenshot 2024-01-06 at 19-21-48 Lesan Playground

Pay attention to the entered data, although we have used insertMany, all relationships are embedded.
In the country, we have embedded the cities in 4 fields separately and with different conditions. And we have embedded users in two fields with different conditions. Screenshot from 2024-01-06 19-07-59

In the cities, we have embedded the respective country. Screenshot from 2024-01-06 19-14-11

In the user schema, for each user, we have embedded the cities he has lived in as a list, the city he is most interested in as an object, and the country of each user as an object. Screenshot from 2024-01-06 19-16-33

The interesting thing about this E2E test is that after the database is filled, you can test a big update in Playground. If you update the country in Playground, 100,000 other documents must be updated along with the country record itself.

before execute main → country → updateCountry: Screenshot from 2024-01-06 19-40-02 executin main → country → updateCountry: Screenshot 2024-01-06 at 19-41-30 Lesan Playground after execute main → country → updateCountry:

relationship sweets in Lesan

shoma tanha ba fieldhaye pure yek schema sar o kar darid va modiriat rabeteha tamaman be sorat khodkar tavasot lesan anjam mishavad. shoma mitavanid bar asas rabeteye yek schema an ra sort ya filter konid shoma baraye daryaft dadaha ba queryhaye pichide asnad besiyar kamtari ra az database jamavari mikonid. (link bedam be tozihat kamel)

relationship bitterness in Lesan

barkhi az rabeteha baes eijad updatehaye besiyar bozorg mishavand. rah hal: 1-eijad rabeteye jadid 2-qq 3-in-memory db

اول راجع به ایمکه رابطه چی هست حرف می‌زنم، بعد می‌گم اس‌کیوال فقط کانکشن برقرار می‌کنه، بعد می‌گم نواس‌کیوال هم فقط امبد می‌کنه و مدیریت درست نداره.

بعد میام راجع به اینکه هر فیلد پر تغییری می‌تونه به رابطه تبدیل بشه حرف می‌زنم، مثال بانک و ثبت احوال کشورها رو می‌گم.

بعد میام راجع به اینکه رابطه‌های دو سر چندتایی نمی‌تونه دو سر بی انتها داشته باشه حرف می‌زنم و چندتا مثال می‌زنم.

بعد راجع به آپدیت شدن رابطه‌ها حرف می‌زنم.

بعد راجع به دیتابیس اینمموری حرف می‌زنم.

بعد راجع به مدیریت کیوکیو حرف می‌زنم.

حتما یادم باشه راجع به اینکه وقتی امبد می‌کنی چقدر دریافت داده‌ها راحت هست هم حرف بزنیم، از اون طرف راجع به اینکه فیلتر کردنشون بر اساس فیلد امبد شده چه معجزه‌ای میکنه هم حرف بزنم

حتما راجع به اینکه چه نکته‌هایی داره طراحی مدل توی لسان حرف بزنم یعنی اینکه بگم رابطه‌ها از یک طرف تعریف می‌شن بعد توی طرف بعدی از همینجا ساید افکت‌هاش مشخص میشه بگم و اینکه نگران نباشن چون توی پلی‌گراند می‌تونن برای یک مدل همه‌ی رابطه‌هایی که داره چه از طرف خودش تعریف شده باشه چه بقیه براش تعریف کرده باشن رو ببینه و یه عکس از پلی‌گراند بذارم، نکته مهمش اینه که بگم همیشه رابطه رو از طرف مهمش درخواست بدن تا بشه هر چقدر می‌خوایم ساید افکت مناسب براش بذاریم

این رو هم بنویسم که در واقع مشکلات آپدیت و دیلیت و اینزرت همین الآن هم هم توی لایه ی کش سرور هم توی سی دی ان ها وجود داره و ما این معضلات رو آوردیم توی لاجیک بک اند و ساده سازی کردیم و در واقع کلی هم از اتلاف انرژی و چیزای دیگه هم اینجا جلوگیری کردیم علاوه بر این اینکه اکثر این عملیات ها رو هم خودکار کردیم.

findOne and find functions

When you want to penetrate only one step in the depth of relationships, the best choices are find and findOne functions.
According to Mongo's behavior, only Aggregation can be used to send a left join query to receive relationships. But considering that all relationships are automatically embedded in Lesan, you can use find and findOne along with aggregation to get one level of relationships, i.e. the father along with all the children.

findOne functions

find a user

lets add getUser functions:

const getUserValidator = () => {
  return object({
    set: object({
      userId: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const getUser: ActFn = async (body) => {
  const {
    set: { userId },
    get,
  } = body.details;

  return await users.findOne({
    filters: { _id: new ObjectId(userId) },
    projection: get,
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "getUser",
  validator: getUserValidator(),
  fn: getUser,
});

findOne functions accept three inputs:

filters which is mongodb findOne query operation
projection which is mongodb projection operation
and optional option which is mongodb findOption

You can also read mongodb findOne section for more information.

executing main → user → getUser: Screenshot 2024-01-08 at 19-21-17 Lesan Playground

Add E2E Test

Like before, for adding getUser request to E2E section you should click on the E2E button, like below picture.

Then, in the E2E section and getUser sequence, you should replace the user id that you set capture in own sequence with default user id. default user id in getUser sequence is like below picture.

The replaced user id is like below picture.

find a city or country

Finding a city or country is exactly the same as finding a user.
Pay attention to the following code:

const getCountryValidator = () => {
  return object({
    set: object({
      countryId: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("country", {
      citiesByPopulation: 1,
      users: 1,
      capital: 1,
    }),
  });
};
const getCountry: ActFn = async (body) => {
  const {
    set: { countryId },
    get,
  } = body.details;

  return await countries.findOne({
    filters: { _id: new ObjectId(countryId) },
    projection: get,
  });
};
coreApp.acts.setAct({
  schema: "country",
  actName: "getCountry",
  validator: getCountryValidator(),
  fn: getCountry,
});

const getCityValidator = () => {
  return object({
    set: object({
      cityId: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("city", { country: 1, lovedByUser: 1 }),
  });
};
const getCity: ActFn = async (body) => {
  const {
    set: { cityId },
    get,
  } = body.details;

  return await cities.findOne({
    filters: { _id: new ObjectId(cityId) },
    projection: get,
  });
};
coreApp.acts.setAct({
  schema: "city",
  actName: "getCity",
  validator: getCityValidator(),
  fn: getCity,
});

The only difference here is in the coreApp.schemas.selectStruct function. The second input of this function, instead of a number, is an object of the relationship key with a value of one number, which explicitly specifies how much this act can penetrate in this particular relationship.
executing main → city → getCity: Screenshot 2024-01-09 at 14-49-33 Lesan Playground

Add E2E Test

For adding getCity request to E2E test section, you should click on the E2E button, like bottom picture.

Then, in the E2E section and getCity sequence, you should replace the city id that you set capture in own sequence with default city id. default city id in getCity sequence is like below picture.

The replaced city id is like below picture.

executing main → country → getCountry: Screenshot 2024-01-09 at 15-03-45 Lesan Playground

You can find full example here and test the findOne method in local computer.

Add E2E Test

Also, for adding getCountry request to E2E test section, you should click on the E2E button, like bottom picture.

Then, in the E2E section and getCountry sequence, you should replace the country id that you set capture in own sequence with default country id. default counry id in getCountry sequence is like below picture.

The replace country id is like below picture.

find functions

find users

lets add getUsers functions:

const getUsersValidator = () => {
  return object({
    set: object({
      page: number(),
      limit: number(),
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const getUsers: ActFn = async (body) => {
  let {
    set: { page, limit },
    get,
  } = body.details;

  page = page || 1;
  limit = limit || 50;
  const skip = limit * (page - 1);
  return await users
    .find({ projection: get, filters: {} })
    .skip(skip)
    .limit(limit)
    .toArray();
};
coreApp.acts.setAct({
  schema: "user",
  actName: "getUsers",
  validator: getUsersValidator(),
  fn: getUsers,
});

find functions accept three inputs:

filters which is mongodb filter query operation
projection which is mongodb projection operation
and optional option which is mongodb findOption

You can also read mongodb find section for more information.
executing main → user → getUsers: Screenshot-2024-01-11-at-13-20-17-Lesan-Playground

Add E2E Test

For adding getUsers request to E2E test section, you should click on the E2E button, like bottom picture.

Well, in the E2E section you can see the getUsers sequence.

find cities or countries

Finding cities or countries is exactly the same as finding users.
Pay attention to the following code:

const getCountriesValidator = () => {
  return object({
    set: object({
      page: number(),
      limit: number(),
    }),
    get: coreApp.schemas.selectStruct("country", {
      citiesByPopulation: 1,
      users: 1,
      capital: 1,
    }),
  });
};
const getCountries: ActFn = async (body) => {
  let {
    set: { page, limit },
    get,
  } = body.details;

  page = page || 1;
  limit = limit || 50;
  const skip = limit * (page - 1);
  return await countries
    .find({ projection: get, filters: {} })
    .skip(skip)
    .limit(limit)
    .toArray();
};
coreApp.acts.setAct({
  schema: "country",
  actName: "getCountries",
  validator: getCountriesValidator(),
  fn: getCountries,
});

const getCitiesValidator = () => {
  return object({
    set: object({
      page: number(),
      limit: number(),
    }),
    get: coreApp.schemas.selectStruct("city", { country: 1, lovedByUser: 1 }),
  });
};
const getCities: ActFn = async (body) => {
  let {
    set: { page, limit },
    get,
  } = body.details;

  page = page || 1;
  limit = limit || 50;
  const skip = limit * (page - 1);
  return await cities
    .find({ projection: get, filters: {} })
    .skip(skip)
    .limit(limit)
    .toArray();
};
coreApp.acts.setAct({
  schema: "city",
  actName: "getCities",
  validator: getCitiesValidator(),
  fn: getCities,
});

The only difference here is in the coreApp.schemas.selectStruct function. The second input of this function, instead of a number, is an object of the relationship key with a value of one number, which explicitly specifies how much this act can penetrate in this particular relationship.
executing main → city → getCities: Screenshot-2024-01-11-at-13-59-22-Lesan-Playground

Add E2E Test

Like before, for adding getCities request to E2E test section, you should click on the E2E button, like bottom picture.

Well, in the E2E section you can see the getCities sequence.

executing main → country → getCountries: Screenshot-2024-01-11-at-13-58-41-Lesan-Playground

You can find full example here and test the find method in local computer.

Add E2E Test

For adding getCountries request to E2E test section, you should click on the E2E button, like bottom picture.

Well, in the E2E section you can see the getCountries sequence.

aggregation functions

We should use Aggregation when we want to penetrate more than one step in the depth of relationships, that is, if we want to go from father to grandson or vice versa.
Don't worry, all the commands you need to penetrate the depths of the relationship and select their fields are automatically generated by Lesan.

The great thing about Aggregation in Lesan is that relationship penetration is always one step behind the client request. For more information about this please see here
We can use aggregation instead of find and findOne.

Get list of documents with aggregation

Pay attention to the code written below:

const getCitiesAggregationValidator = () => {
  return object({
    set: object({
      page: number(),
      take: number(),
      countryId: optional(objectIdValidation),
    }),
    get: coreApp.schemas.selectStruct("city", 3),
  });
};
const getCitiesAggregation: ActFn = async (body) => {
  const {
    set: { page, take, countryId },
    get,
  } = body.details;
  const pipeline = [];

  pipeline.push({ $skip: (page - 1) * take });
  pipeline.push({ $limit: take });
  countryId &&
    pipeline.push({ $match: { "country._id": new ObjectId(countryId) } });

  return await cities
    .aggregation({
      pipeline,
      projection: get,
    })
    .toArray();
};

coreApp.acts.setAct({
  schema: "city",
  actName: "getCitiesAggregation",
  validator: getCitiesAggregationValidator(),
  fn: getCitiesAggregation,
});

In the code above, we have used aggregation to find the cities.
As you can see, we have added two pipelines to create pagination by using page and take inputs, but these two pipelines are not all that is sent to the database. Lesan automatically creates lookup, unwind and projection pipelines based on get input. So that we can establish a join between the schemas and select and return the data requested by the user.

If this request is sent to the server:

{
  "body": {
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": ""
    },
    "body": {
      "service": "main",
      "model": "city",
      "act": "getCitiesAggregation",
      "details": {
        "get": {
          "_id": 1,
          "name": 1,
          "country": {
            "_id": 1,
            "name": 1
          },
          "users": {
            "_id": 1,
            "name": 1
          }
        },
        "set": {
          "page": 1,
          "take": 10
        }
      }
    }
  }
}

these pipelines will be created:

[
  {
    "$project": {
      "_id": 1,
      "name": 1,
      "country": { "_id": 1, "name": 1 },
      "users": { "_id": 1, "name": 1 }
    }
  }
]

And if this request is sent to the server:

{
  "body": {
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": ""
    },
    "body": {
      "service": "main",
      "model": "city",
      "act": "getCitiesAggregation",
      "details": {
        "get": {
          "_id": 1,
          "name": 1,
          "country": {
            "_id": 1,
            "name": 1,
            "cities": {
              "_id": 1,
              "name": 1
            },
            "citiesByPopulation": {
              "name": 1,
              "_id": 1
            },
            "capital": {
              "_id": 1,
              "name": 1
            }
          },
          "users": {
            "_id": 1,
            "name": 1,
            "livedCities": {
              "name": 1,
              "_id": 1
            },
            "country": {
              "_id": 1,
              "name": 1
            }
          },
          "lovedByUser": {
            "_id": 1,
            "name": 1
          }
        },
        "set": {
          "page": 1,
          "take": 10
        }
      }
    }
  }
}

these pipelines will be created:

[
  {
    "$lookup": {
      "from": "country",
      "localField": "country._id",
      "foreignField": "_id",
      "as": "country"
    }
  },
  {
    "$unwind": {
      "path": "$country",
      "preserveNullAndEmptyArrays": true
    }
  },
  {
    "$lookup": {
      "from": "user",
      "localField": "users._id",
      "foreignField": "_id",
      "as": "users"
    }
  },
  {
    "$project": {
      "_id": 1,
      "name": 1,
      "country": {
        "_id": 1,
        "name": 1,
        "cities": {
          "_id": 1,
          "name": 1
        },
        "citiesByPopulation": {
          "name": 1,
          "_id": 1
        },
        "capital": {
          "_id": 1,
          "name": 1
        }
      },
      "users": {
        "_id": 1,
        "name": 1,
        "livedCities": {
          "name": 1,
          "_id": 1
        },
        "country": {
          "_id": 1,
          "name": 1
        }
      },
      "lovedByUser": {
        "_id": 1,
        "name": 1
      }
    }
  }
]

Note that pipelines are always one step behind the request, and send indexed lookup with _id for anything. because we embed all relations.

Because we have given the second input 3 in the coreApp.schemas.selectStruct("city", 3) function, we can penetrate one more step in the depth of relationships, you can send more complex queries in the playground.

You can find full example here and test the aggregation method in local computer.

executing main → city → getCitiesAggregation: aggregation-cities

Add E2E Test

Like before, for adding getCitiesAggregation request to E2E test section, you should click on the E2E button, like bottom picture.

Then, in the E2E section and getCitiesAggregation sequence, you should replace the country id that you set capture in own sequence with default country id. default country id in getCitiesAggregation sequence is like below picture.

The replaced country id is like below picture.

Get a one document with aggregation

Because we may request the relations of a document more than one step and if we want to use lookup between two schemas, we have to use aggregation even to receive a document.

Enter the following code to find a user:

const getUserAggregationValidator = () => {
  return object({
    set: object({
      userId: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("user", 2),
  });
};
const getUserAggregation: ActFn = async (body) => {
  const {
    set: { userId },
    get,
  } = body.details;
  const pipeline = [];

  pipeline.push({ $match: { _id: new ObjectId(userId) } });

  return await users
    .aggregation({
      pipeline,
      projection: get,
    })
    .toArray();
};

coreApp.acts.setAct({
  schema: "user",
  actName: "getUserAggregation",
  validator: getUserAggregationValidator(),
  fn: getUserAggregation,
});

Note that the returned information will still be in an array but with one member.

You can find full example here and test the aggregation method in local computer.

executing main → user → getUserAggregation: aggregation-user

Add E2E Test

For adding getUserAggregation request to E2E test section, you should click on the E2E button, like bottom picture.

Then, in the E2E section and getUserAggregation sequence, you should replace the user id that you set capture in own sequence with default user id. default user id in getUserAggregation sequence is like below picture.

The replaced user id is like below picture.

`findOneAndUpdate` functions

Updating is the most challenging issue in Lesan. Because by updating one document, thousands or maybe millions of other documents may also be updated. Don't worry, this is done automatically by Lesan. And also for complex scenarios where millions of documents need to be updated, we have created various solutions.

Let's explore a few scenarios.

Best case "Update a user":

const updateUserValidator = () => {
  return object({
    set: object({
      _id: objectIdValidation,
      name: optional(string()),
      age: optional(number()),
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const updateUser: ActFn = async (body) => {
  const { name, age, _id } = body.details.set;
  const setObj: { name?: string; age?: number } = {};
  name && (setObj.name = name);
  age && (setObj.age = age);

  return await users.findOneAndUpdate({
    filter: { _id: new ObjectId(_id) },
    projection: body.details.get,
    update: { $set: setObj },
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "updateUser",
  validator: updateUserValidator(),
  fn: updateUser,
});

When we were defining user relationships, we said that each user has a relationship with the cities he lived in. In defining this relationship, we said that we store the last 50 users who lived in these cities in the city table. So it is possible that the user who is updated may be in the list of these 50 users in several cities. So we have to find the cities where this user lives and update the list of users in those cities.
If we set the order of saving this list of 50 items based on a field from the user and the same field has been updated, the story will be a little more complicated. Because it is possible that if this user is in the list of 50, he will be removed from this list due to the updating of this field and another user who has suitable conditions will replace this user. For more information please read here.

All things will be the same for the country.

You can find full example here and test the findOneAndUpdate method in local computer.

before executing main → user → updateUser: db-user-update

executing main → user → updateUser: db-user-updating

after executing main → user → updateUser: db-user-updated

Add E2E Test

Like before, for adding updateUser request to E2E section you should click on the e2e button (like bottom picture) to add your request to E2E section.

Then, in the E2E section and updateUser sequence, you should replace the user id that you set capture in own sequence with default user id. default user id in updateUser sequence is like below picture.

The replaced user id is like below picture.

Worse case "Update a country":

const updateCountryValidator = () => {
  return object({
    set: object({
      _id: objectIdValidation,
      name: optional(string()),
      abb: optional(string()),
      population: optional(number()),
    }),
    get: coreApp.schemas.selectStruct("country", 1),
  });
};
const updateCountry: ActFn = async (body) => {
  const { name, abb, population, _id } = body.details.set;
  const setObj: { name?: string; abb?: string; population?: number } = {};
  name && (setObj.name = name);
  abb && (setObj.abb = abb);
  population && (setObj.population = population);

  return await countries.findOneAndUpdate({
    filter: { _id: new ObjectId(_id) },
    projection: body.details.get,
    update: { $set: setObj },
  });
};
coreApp.acts.setAct({
  schema: "country",
  actName: "updateCountry",
  validator: updateCountryValidator(),
  fn: updateCountry,
});

If the country is updated in a real scenario, the number of documents that need to be updated along with the country is likely to be very large. Because all users and cities of that country must be updated.

You can find full example here and test the findOneAndUpdate method in local computer.

before executing main → country → updateCountry: before-update-country

executing main → country → updateCountry: updating-country

after executing main → country → updateCountry: after-update-country

Add E2E Test

Like before, for adding updateCountry request to E2E section you should click on the e2e button (like bottom picture) to add your request to E2E section.

Then, in the E2E section and updateCountry sequence, you should replace the country id that you set capture in own sequence with default country id. default country id in updateCountry sequence is like below picture.

The replaced country id is like below picture.

Lesan's solution to the update challenge

As you have seen, we face a big problem for updating the country and millions of documents may need to be updated by updating one document. This is the biggest challenge in Lesan and we propose 3 solutions to solve this problem:

QQ solutions

QQ stands for query queue, a queue of commands to be sent to the database. We use QQ to chunk millions of updates. In this way, we take a section of several hundred thousand that we guess should be updated immediately and perform the update, then we store the ID of the last updated document along with the necessary commands for updating in QQ. And we do another part of the update whenever hardware resources are low on contention.

In-memmory DB solutions

Because we have detailed relationship information, we can know when sending information to the customer that the information sent has changes in QQ. As a result, by saving the changes in an in-memory database, we can correct the sent information in the same RAM and send it to the client, without changing the actual data in the hard disk.

Make new relation solutions

Perhaps the most beautiful thing about database relations is here.
In Lesan, after checking the data model, we can convert frequently changing fields into a new relationship.
Going back to the previous example, our real problem was updating a country because millions of documents needed to be updated.
In our example, each country had the following pure fields:

name
abb
population

The name and abb fields usually do not change, in fact, in our example, they never change, but the population field may change a lot, imagine that we want to have the updated population of each country every second, that is, all countries are updated every second. And by updating each country, all the cities and users belonging to that country must be updated. Well, this is almost impossible.
But if we convert the population field into a new schema and create a relationship with the country for it, all problems will be solved.
Pay attention to the following code:

const populationPure = {
  population: number(),
  type: enums(["City", "Country"]),
};

const populationRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      populations: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
  city: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      populations: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
    },
  },
};

const populations = coreApp.odm.newModel(
  "population",
  populationPure,
  populationRelations
);

Now we can remove the population field from both the pure fields of the city and the pure fields of the country. But there is still the population field in both the country and the city, and we can write any type of filter or sort for the city and country schemas based on the population. Even better, now we have a list of the last 50 population records for each country and each city, and we can find, for example, countries that have added more than 100 people to their population in the last minute, without sending a complex query to the database.

And the most important thing is that now, with the population change, instead of millions of documents, only two documents change.
Because to change the population, we make a new record for the population and store this new record only in the country or city that belongs to it in the populations list. And we no longer need to update thousands of cities or millions of users.

deleteOne functions

Deletion has the same problems as update.

Delete a User

Pay attention to the following code:

const deleteUserValidator = () => {
  return object({
    set: object({
      _id: string(),
    }),
    get: object({
      success: optional(enums([0, 1])),
    }),
  });
};

const deleteUser: ActFn = async (body) => {
  const {
    set: { _id },
    get,
  } = body.details;
  return await users.deleteOne({
    filter: { _id: new ObjectId(_id) },
  });
};

coreApp.acts.setAct({
  schema: "user",
  actName: "deleteUser",
  validator: deleteUserValidator(),
  fn: deleteUser,
});

If you remember, when we defined a relationship for the user, we gave it the following object as a relationship:

{
  livedCities: {
    optional: false,
    schemaName: "city",
    type: "multiple",
    sort: {
      field: "_id",
      order: "desc",
    },
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 50,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },

  country: {
    optional: false,
    schemaName: "country",
    type: "single",
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 50,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },
}

Fortunately, all the relationships that exist for the user are the ones we have defined above, and there is no relatedRelation for the user. user-schema-for-delete

That's why we said fortunately, because if a document has relatedRelations, by deleting that document, some documents may be meaningless or not used. For example, if we want to delete a country in the example we have completed so far, the cities belonging to that country will become meaningless data.

There is no problem for users and we can simply use delete without other data being unused. But by deleting each user, we have to check its mainRelations and if the user is stored as an embed, delete the user there, and if another user needs to be added to the embed list, add the other user as well.

In our example, we have to check the embedded list of users in the cities where the user lives, as well as the list of users in the country belonging to that user.

You can find full example here and test the deleteOne method in local computer.

bfore execut main → user → deleteUser:
15-0-before-execute-delete-user

executing main → user → deleteUser:
15-1-delete-user-executing

after execut main → user → deleteUser:
15-2-after-delete-user

Add E2E Test

For adding deleteUser request to E2E section you should click on the e2e button (like bottom picture) to add your request to E2E section.

Then, in the E2E section and deleteUser sequence, you should replace the user id that you set capture in own sequence with default user id. default user id in deleteUser sequence is like below picture.

The replaced country id is like below picture.

Delete a Country

What if we want to remove a country? Although we have not defined any relationship for the country, both the city and the user have created relationships with the country.

const countryRelations = {};

const cityRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single" as RelationDataType,
    relatedRelations: {
      cities: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "_id",
          order: "desc" as RelationSortOrderType,
        },
      },
      citiesByPopulation: {
        type: "multiple" as RelationDataType,
        limit: 50,
        sort: {
          field: "population",
          order: "desc" as RelationSortOrderType,
        },
      },
      capital: {
        type: "single" as RelationDataType,
      },
    },
  },
};

const userRelations = {
  livedCities: {
    optional: false,
    schemaName: "city",
    type: "multiple",
    sort: {
      field: "_id",
      order: "desc",
    },
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 50,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },

  country: {
    optional: false,
    schemaName: "country",
    type: "single",
    relatedRelations: {
      users: {
        type: "multiple",
        limit: 50,
        sort: {
          field: "_id",
          order: "desc",
        },
      },
    },
  },
};

Screen-Shot-1402-10-28-at-10 04 16 As we said earlier, the data created based on this country will be useless. Here the cities and users created based on this country become useless. Pay attention to the following code:

const deleteCountryValidator = () => {
  return object({
    set: object({
      _id: string(),
    }),
    get: object({
      success: optional(enums([0, 1])),
    }),
  });
};
const deleteCountry: ActFn = async (body) => {
  const {
    set: { _id },
    get,
  } = body.details;
  return await countries.deleteOne({
    filter: { _id: new ObjectId(_id) },
  });
};
coreApp.acts.setAct({
  schema: "country",
  actName: "deleteCountry",
  validator: deleteCountryValidator(),
  fn: deleteCountry,
});

By adding the above code and running the software and sending a request to delete a country, and finally if that country has a city or user, we will encounter the following error:

{
  body: {
    message: please clear below relations status before deletion:  [ {  schemaName:  country,   type:  single,   optional:  false,   fieldName:  country,   collection:  city,   doc:  {   _id:  65a3d213e18957d8c176ffb4,    name:  Hamedan,    population:  900000,    abb:  HM,    country:  {    _id:  65a3d213e18957d8c176ffb2,     name:  Islamic Republic Of Iran,     population:  89000000,     abb:  IR   },    users:  [    {     _id:  65a3d213e18957d8c176ffc0,      name:  Mohammad Sheida,      age:  20    },     {     _id:  65a3d213e18957d8c176ffbf,      name:  Elham Afshar,      age:  25    },     {     _id:  65a3d213e18957d8c176ffbd,      name:  Saeid Ghal,      age:  27    },     {     _id:  65a3d213e18957d8c176ffbc,      name:  Ehsan Akefi,      age:  20    },     {     _id:  65a3d213e18957d8c176ffbb,      name:  Amir Meyari,      age:  30    }   ]  } },  {  schemaName:  country,   type:  single,   optional:  false,   fieldName:  country,   collection:  user,   doc:  {   _id:  65a3d213e18957d8c176ffb7,    name:  Syd Amir,    age:  36,    livedCities:  [    {     _id:  65a3d213e18957d8c176ffb4,      name:  Hamedan,      population:  900000,      abb:  HM    },     {     _id:  65a3d213e18957d8c176ffb5,      name:  Tehran,      population:  1000000,      abb:  TH    }   ],    country:  {    _id:  65a3d213e18957d8c176ffb2,     name:  Islamic Republic Of Iran,     population:  89000000,     abb:  IR   }  } }]
  },
  success: false
}

We have two ways:

Delete all these documents related to this country one by one.
Set the hardCascade option to true in the deleteOne function. We change the above code as follows:

return await countries.deleteOne({
  filter: { _id: new ObjectId(_id) },
  hardCascade: true,
});

This will cause all the dependent documents and the dependent documents of these dependent documents to be deleted recursively.

You can find full example here and test the deleteOne method in local computer.

bfore execut main → country → deleteCountry: delete-country-before

executing main → country → deleteCountry: deleteing-country

after execut main → country → deleteCountry: delete-country-after

Add E2E Test

Like before, for adding deleteCountry request to E2E section you should click on the e2e button (like bottom picture) to add your request to E2E section.

Then, in the E2E section and deleteCountry sequence, you should replace the country id that you set capture in own sequence with default country id. default country id in deleteCountry sequence is like below picture.

The replaced country id is like below picture.

insertMany functions

Another surprise of Lesan is the use of insertMany while all relationships can be embedded correctly. Consider the following example:

const addCitiesValidator = () => {
  return object({
    set: object({
      multiCities: array(object(countryCityPure)),
      country: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("city", 1),
  });
};
const addCities: ActFn = async (body) => {
  const { country, multiCities } = body.details.set;

  return await cities.insertMany({
    docs: multiCities,
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          cities: true,
          citiesByPopulation: true,
          capital: false,
        },
      },
    },
  });
};
coreApp.acts.setAct({
  schema: "city",
  actName: "addCities",
  validator: addCitiesValidator(),
  fn: addCities,
});

There are two important points in the above code:

The multiCities input is an array of pure city field objects. Therefore, it must have the following value:
```
"multiCities": [
  {
    "name": "Beirout",
    "abb": "BI",
    "population": 20000000
  },
  {
    "name": "Baalbak",
    "abb": "BA",
    "population": 850000
  }
]
```
The beautiful thing here is that before the addCities function is executed, all data, including multiCities, is validated. This feature allows us to validate the wrong data before sending any command to the database.
The second point is that we explicitly set the capital relation in the city relatedRelation to false. Because we do not know which city is going to be chosen as the capital. In general, one-to-one relations in insertMany should always be false because they destroy the concept of insertMany and cause its relatedRelations to be updated once for every new document that is added, which is usually wrong.

Pay attention that all changes are sent to the database with an aggregation pipeline.

You can find full example here and test the insertMany method in local computer.

bfore execut main → city → addCities: insertMany-before-execut-City

executing main → city → addCities: insertMany-executing-City

after execut main → city → addCities: insertMany-after-execut-City

Let us use insertMany to add users:

const addUsersValidator = () => {
  return object({
    set: object({
      multiUsers: array(object()),
      country: objectIdValidation,
      livedCities: array(objectIdValidation),
      lovedCity: objectIdValidation,
    }),
    get: coreApp.schemas.selectStruct("user", 1),
  });
};
const addUsers: ActFn = async (body) => {
  const { country, multiUsers, livedCities, lovedCity } = body.details.set;
  const obIdLivedCities = livedCities.map((lp: string) => new ObjectId(lp));

  return await users.insertMany({
    docs: multiUsers,
    projection: body.details.get,
    relations: {
      country: {
        _ids: new ObjectId(country),
        relatedRelations: {
          users: true,
        },
      },
      livedCities: {
        _ids: obIdLivedCities,
        relatedRelations: {
          users: true,
        },
      },
      mostLovedCity: {
        _ids: new ObjectId(lovedCity),
        relatedRelations: {
          lovedByUser: true,
        },
      },
    },
  });
};
coreApp.acts.setAct({
  schema: "user",
  actName: "addUsers",
  validator: addUsersValidator(),
  fn: addUsers,
});

In the code above, there are almost all types of relationships that we can use in insertMany.

There is a one-to-many relationship between users and countries, that is, the country field receives an ID, and after finding the relevant country, its pure fields are stored in the user. On the country side, in two multiple lists, the user is stored once with ID sorted from last to first(users field) and once with age sorted from oldest to youngest(usersByAge).
Also, users have a many-to-many relationship with the cities they have lived in and receive a set of city IDs, and after finding those cities, the pure fields of each one are stored in an array called livedCities.On the city side, the pure fields of the entered users are stored in the users field for each city.
The user has another relationship with the city, which is a one-to-many relationship. In this way, the user saves the city he likes the most in the mostLovedCity field. And on the city side, the list of entered users is stored in the field of lovedByUser.

bfore execut main → user → addUsers: insertMany-user-before

executing main → user → addUsers: insertMany-user-executing

after execut main → user → addUsers:
insertMany-user-after

Pay attention that all changes are sent to the database with an aggregation pipeline.

You can find full example here and test the insertMany method in local computer.

The implementation of insertMany for the country is also very simple because no relationship is needed to create the countries, we will leave the implementation of this part of the code to you.
If you want to see a real insertMany code, you can see the code implemented for the benchmark here.
The interesting thing is that due to the correct definition of the relationship in Lesan, the implementation of the benchmark code with insertMany was very simple, while this task was a bit complicated in the rest of the platforms.
Also, the time spent for entering data in Lesan is interesting, because this time is very short due to insertMany.

Playground

First Encounter

When you first enter the playground, you will see 3 part :

PlayGround

Part One : Tabs

At the top of the page there are tabs that allow you to do different things at the same time without losing information. You can make and use as many tabs you need(2) with add button(1) and close them at any time with close button(3). By refreshing the page, the tabs information does not disappear and after the tab refresh the tabs are fully accessible.

Tabs

On the left side is the sidebar, with 3 select box that are used to select the service(1), Schema(2) and Action(3), respectively. It should be noted that the selection of Schema and act is inactive until the service is selected.

Sidebar

After selecting the service, Schema and act, another column is displayed, which includes 2 sections of set fields(1) and get fields(2). In the set fields, you fill in the values you need(1-1) and in the get field section you choose the values you want to get and also we either want the field to set the field equal to one or we do not want the amount to be zero(2-1). After completing the sections of the set fields and get fields set, by pressing the Send Button(3), the results we have had in the response section are shown in the response section.

Second Sidebar

Response

Response Section

At the top of the response section, we have access to 3 button, copy Request(1), copy Response(2) and Run E2E Test(3) that send the request to the E2E Test modal that we will explain below.

Also we can see the status of the request who can be true with green light and false with red loght(4).

At the top-right of the body response we can access to the time of the request with took(5).

Response-Detail

Part Three: Buttons

In this section we will see 6 buttons that we will explain below :

Buttons

Before explain 6 buttons, Notice that in every modal we can use the close button(1) to close the modal. Modals

Also we can use change size button(2) to see modal in full screen or window size. Modals-1

Modals-2

Refetch button:

Pressing it all the data is renewed once.

Reffetch Button

Settings button:

Setting Button

Pressing that modal of settings open for us to see two parts of the Fetch Config(1) and the Set Headers(2).

Setting Detail

In the fetch config section, we can set an Url(1) and press Apply Button(2) that we can bring the lesan to different addresses.

Setting Detail-1

In the set headers we can also determine the key(1) and value(2). also we can press Add Header(3) button to add many new Key and Value and set them wit Apply(4) button.

Setting Detail-2

History button:

By pressing History button, we enter the modal history in which we have access to all the Requests(1) as well as and Responses(2) the results.

In top-right of the Request section we can see the Date Of The Request and also in top-left of the Response we can see the Time Of Response.

In top-right of the every part of the request we can delete the this part with Delete button(5).

Also we can clean all the request by press the Dustbin Button(6).

History

In the request section we access to Model and Act(1) of the request and Show Button(2) to see the detail of the request and response.

History-1

We can hide the details with Hide button: History-2

In the response section, we can see the Status Of The Response(1) that can be true or false and also we can reuse of the request with Use Button(2).

History-3

E2E Test button:

In E2E test modal, we see two section, section one include Five Button that the top-left of the modal and section two its be Eeach Sequence of the test.

E2E

We start with the section one, in this section we have five button include Add(1), Run E2E Test(2), Import(3), Export(4) and Help(5).

E2E-1

With Add Button we can create a new Sequence for test. we can add how much we need sequence for test.

E2E-2

With Run E2E Test Button we can run the test. we explain this after.

With Import Button we can import the pervious tests and reuse them.

E2E-3

With Export Button we can export existing tests for use them for anothe test.

And with Help Button we go to playground document that we can see how to work with E2E modal.

In each sequence, we can see 2 part, Set Test Body And Headers(1) and Set Repeat Time, Capture Variables(2) E2E-4

Part 1 is a Set Test Body And Headers that we can write and set body and headers for test. also we can use the faker for test. for example you can see that we use faker for this sequense: E2E-4

In Part two we can Set Repeat Time(1) of the test with + or - button or write number we want in input. also we can use Add Capture(2) Button for set how many capture we want to the sequence for test. E2E-5

After press the Add Capture we can see a part that include two input, include set a variable name(1) that we can see an Example(2) to how fill this input and another input, is set a value for variable(3) that we can see an Example(4) to how fill this input. Also we can set capture couple model. E2E-6

We have four button in top-right of the each sequence test: E2E-7

Duplicate Button(1) that we can duplicate sequence. E2E-8

Move Buttuns(2)(3), with this buttons we can move the sequense to top or bottom.

Delete Button(4), with this button we can delete each sequence.

After write the sequences test, we can go to see the resulst of the each sequence test by click on the Run E2E Test Button and we see this:
E2E-9

First thing that we see is Back Button and second is Export Button at the top-left of the modal.

third one is a Information section that we can see all information of the sequence tests.

E2E-10

The Information section have three part, Requests(1),Times(2) and Captures Information(3).

E2E-11

Requests part include All Request Count(1) , All Request Time(2), All Success Request(3) and All Fails Request(4). E2E-12

Times part include two section, Best and Worst. in each section we can see the Best/Worst request time, sequence number of the best/worst request that when click on number, we scroll to that sequence number, request number that include number of the request in sequence, model and act.

E2E-13

Captures Information part include every capture items that we set. in this part we can see the Key(1), Captured From(2), Value Of(2), Model(2), Act(2) and Captured Inside Sequnce Number.

E2E-14

After Information section, we can access every sequence that each of sequence have two part, Description(1) and Body Header(2).

E2E-15

Description have five part include Request(1) that include All Request Count, Success/Fail that show the how many of request is success/Fail, All Request Time and Avrage Time For Each Request, Best(2) and Worst(3) that include Best/Worst Time and request nmber, Capture Items(4) that include key,value,model,act,sequence number, Using Capture Items(5) that include key,captured from, value,act and sequence number.

E2E-16

Body Header have headers,body of the each sequence(1), number of sequence(2) at the top-right and change button(3) at the top-left.

E2E-17

When click on Change Button we can see and access to the Request(1) and Response(2) that in Request section we can see the pure request(3) and at the Response section we can see the body of the response and success status of Responsewhich the false or true(4).

At the top-right of the Response section we can see the time of the Respone(5).

At the Bottom-center, we can access to the pagination(6) to move on the Requests or write the specefic Request number to access the Request.

Also when click on change button(7) to go back to the Body Header and Description.

E2E-18

Schema button:

In Schema modal we have access to all the Schema project. For example, we can see the country,city and user. Schema

Country have pure(1) and related relations(2). Schema-1

And pure have _id(1), name(2), population(3), abb(4). Schema-2

And Also related relations have cities asc(1), cities desc(2), cities by pop asc(3), cities by pop desc(4), capital city(5), users(6), users by age(7). Schema-3

Also by hovering on question icon we can see the relations. Schema-4

We see the country, lets see the city. city have pure(1), main Relation(2), related relations(3). Schema-5

Pure have _id(1), name(2), population(3), abb(4). Schema-6

main relations have country and country have _id, name, population and abb. Schema-7

Also by hovering on question icon we can see the relations. Schema-8

And related relations have users(1) and loved user(2). Schema-9

Users have _id, name, age. Schema-10

Act button:

Like Schema modal in Act modal , we have access to all the Act of the project. Act have main and main have country(1), city(2), user(3). Act-1

And country have add country(1), update country(2), add countries(3), get countries(4), delete country(5). Act-2

Let see the add country. we can see the set(1) and get(2). Act-3

Set have name(1), population(2) and abb(3). Act-4

And get have _id(1), name(2), population(3), abb(4), users(5). Act-4

Request flow in Lesan

We only accept two types of HTTP methods in Lesan:

GET
POST

GET Requests:

We accept two models of GET requests:

Requests sent to serve a static document.
In order to receive a static document with a GET request, you must first allow its path to Lesan, for this you only need to add the following settings when calling the runServer function:
```
  coreApp.runServer({ staticPath: ["/pictures", "/videos"] });
```
The staticPath key receives an array of strings

Now all the files in the pictures or videos folder will be accessible by sending a GET request, for example:
```
https://www.xyz.com/pictures/avatar.png
```
Requests sent to receive playground static documents or access to the playground itself.
In order to access the playground, you must set the playground entry in the runServer function equal to true.
```
  coreApp.runServer({ playground: true });
```
The playground key receives a boolean value.

Now you can access the playground by sending a GET request to an address similar to http://localhost:1367/playground.
Note that the following addresses will be accessible together with the playground and will send the necessary data to run the playground:
- /playground/static/index.css
  which sends the necessary styles for the UI in the playground.
- /playground/static/bundle.js
  which sends a JS bundle of all the codes needed to run the playground.
- /playground/static/get/schemas
  which sends two JSON data, schemas and acts, which contain all the information we need in the playground to send requests to the server.

POST Requests:

We accept two models of POST requests:

Requests sent to receive data from the server (in fact, these requests are the main requests sent to Lesan).
Requests sent to upload a document.

Receive data

To receive data from the Lesan server, you must send a POST request to the final address of Lesan. In the body of this request, must be an object in JSON format with the following keys:

The service key is used to select one of the microservices set on the application. This key is optional and by default the value of main is placed in it.
The model key is used to select one of the Models added to the application.
The act key is used to select one of the Acts added to the application.
The details key is used to receive data to be sent from the client side along with data to be delivered to users. This key has two internal keys called get and set, we talked a little about it before.
- set: It contains the information we need in the Act function.
- get: Contains selected information that the user needs to be returned. This selection is based on zero or one. Therefore, we can pass this object directly to MongoDB projection.

An example of this JSON object is as follows:

{
  "service": "main",
  "model": "country",
  "act": "addCountry",
  "details": {
    "set": {
      "name": "Iran",
      "population": 85000000,
      "abb": "IR"
    },
    "get": {
      "_id": 1,
      "name": 1,
      "population": 1,
      "cities": {
         "name": 1,
         "population": 1,
      }
    }
  }
}

This request finally reaches the function we specified for Act to extract the necessary information from it and return the information requested by the user.
If you remember, we set up each Act as follows:

coreApp.acts.setAct({
  schema: "user",
  actName: "addUser",
  validator: addUserValidator(),
  fn: addUser,
  preValidation: [setUser, checkLevel],
  preAct: [justAdmin],
  validationRunType: "create",
});

Upload documents

For uploading a document you should send a POST request to Lesan endpoint.

Lesan vs GraphQL

All the advantages of Lesan

راجع به فانکشنال پروگرمینگ حتما بگم و اینهارو توش توضیح بدم :
مثلا وقتی یه چیزی newModel میشه دیگه همه‌ی فانکشن‌های توی odm براش در دسترس هست با یه ساینتکس قابل فهم
بعد راجع به اسکیماها و اکتها هم همین فرایند newModel رو بگم
بعد راجع به بعضی چیزای دیگه مثل preAct و preValidation و حتی فانکشن‌هایی که برای ولیدیشن میدیم که فانکشن هست هم توضیح بدم که یعنی میتونه اونجا از hof یا curriyng استفاده کنه

Implement an advanced project