Quick Start

Source Files

This page is generated from the following source files:

• README.md
• examples/deno-app/src/main.ts
• examples/bun-app/src/main.ts
• examples/node-app/src/main.ts
• examples/document/01-simplest.ts
• examples/document/02-impement-first-fn.ts
• examples/document/06-1-find-one.ts
• examples/document/09-1-deleteOne.ts
• examples/document/09-2-deleteOne.ts
• examples/document/10-2-insertMany.ts

Lesan is a high-performance, cross-platform framework designed to simplify NoSQL database operations while providing GraphQL-like client-server connectivity. The framework natively supports Node.js, Bun, and Deno runtimes with zero configuration overhead, enabling developers to write code once and run it anywhere (README.md:9).

Prerequisites

Before installing Lesan, ensure the following requirements are met:

Runtime Environment:

• Node.js: Version 16+ (for ES modules and top-level await support)
• Bun: Latest stable version
• Deno: Version 1.30+ (for npm: specifier support)

Database:

• MongoDB instance (local or remote) accessible via connection string

Development Tools (Node.js only):

• tsx or ts-node for TypeScript execution
• Package manager: npm, yarn, or pnpm

The framework connects to MongoDB using the standard MongoDB connection string format. The default local development connection uses mongodb://127.0.0.1:27017/ as shown in all example implementations (examples/node-app/src/main.ts:8, examples/bun-app/src/main.ts:8, examples/deno-app/src/main.ts:8).

Installation

Lesan provides platform-specific installation methods for each supported runtime. The framework requires both the lesan package and the mongodb driver as dependencies.

Node.js Installation

bash
1npm install lesan mongodb

(README.md:49-51)

Bun Installation

bash
1bun add lesan mongodb

(README.md:55-57)

Deno Installation

Deno uses direct imports without a package installation step. Import the framework using the npm: specifier in the source file:

typescript
1import { lesan } from "npm:lesan";
2import { MongoClient } from "npm:mongodb";

(README.md:61-64, examples/deno-app/src/main.ts:1-2)

Installation Summary Table

Minimal Server Setup

The fastest path to a running Lesan application involves three core steps: initializing the application instance, connecting to MongoDB, and starting the HTTP server.

Step 1: Create Application File

Create a file named main.ts with the following minimal configuration:

typescript
1import { lesan, MongoClient } from "https://deno.land/x/lesan@v0.0.98/mod.ts";
2
3const coreApp = lesan();
4
5const client = await new MongoClient("mongodb://127.0.0.1:27017/").connect();
6
7const db = client.db("documentExamples");
8
9coreApp.odm.setDb(db);
10
11coreApp.runServer({ port: 1366, typeGeneration: false, playground: true });

(examples/document/01-simplest.ts:1-11)

Step 2: Run the Server

Execute the application using the runtime-specific command:

Node.js:

bash
1npx tsx main.ts

(README.md:263-265)

Bun:

bash
1bun run main.ts

(README.md:269-271)

Deno:

bash
1deno run -A main.ts

(README.md:275-277)

Step 3: Verify Server Status

Upon successful startup, the terminal displays the following output:

bash
1HTTP webserver running.
2please send a post request to http://localhost:1366/lesan
3you can visit playground on http://localhost:1366/playground
4
5Listening on http://localhost:1366/

(README.md:281-287)

The server exposes two primary endpoints:

• API Endpoint: http://localhost:1366/lesan (POST requests for data operations)
• Playground UI: http://localhost:1366/playground (interactive query builder and tester)

Define Models and Actions

Lesan uses a schema-first approach where data models and action functions define the application's capabilities. Models represent MongoDB collections, while actions encapsulate business logic for data manipulation.

Model Definition

Models define the structure and validation rules for MongoDB documents. The newModel function accepts three parameters: model name, pure schema (field definitions), and relations configuration.

typescript
1const userPure = {
2  name: string(),
3  age: number(),
4  email: string(),
5};
6
7const users = app.odm.newModel("user", userPure, {});

(examples/bun-app/src/main.ts:12-19)

Action Implementation

Actions combine validation logic with business operations. Each action requires:

1. Validator function: Defines input schema and output projection
2. Action function: Implements the data operation
3. Registration: Links the action to a schema and name

typescript
1const addUserValidator = () => {
2  return object({
3    set: object(userPure),
4    get: app.schemas.selectStruct("user", 1),
5  });
6};
7
8const addUser: ActFn = async (body) => {
9  const { name, age, email } = body.details.set;
10  return await users.insertOne({
11    doc: { name, age, email },
12    projection: body.details.get,
13  });
14};
15
16app.acts.setAct({
17  schema: "user",
18  actName: "addUser",
19  validator: addUserValidator(),
20  fn: addUser,
21});

(examples/bun-app/src/main.ts:21-42)

Complete Example with Country Model

A more comprehensive example demonstrates model relationships and complete action lifecycle:

typescript
1const countryPure = {
2  name: string(),
3  population: number(),
4  abb: string(),
5};
6
7const countryRelations = {};
8
9const countries = coreApp.odm.newModel(
10  "country",
11  countryPure,
12  countryRelations,
13);
14
15const addCountryValidator = () => {
16  return object({
17    set: object(countryPure),
18    get: coreApp.schemas.selectStruct("country", { users: 1 }),
19  });
20};
21
22const addCountry: ActFn = async (body) => {
23  const { name, population, abb } = body.details.set;
24  return await countries.insertOne({
25    doc: {
26      name,
27      population,
28      abb,
29    },
30    projection: body.details.get,
31  });
32};
33
34coreApp.acts.setAct({
35  schema: "country",
36  actName: "addCountry",
37  validator: addCountryValidator(),
38  fn: addCountry,
39});

(examples/document/02-impement-first-fn.ts:1-58)

Running the Application

Server Configuration Options

The runServer function accepts configuration parameters for port, playground access, and type generation:

typescript
1app.runServer({
2  port: 8080,
3  playground: true,
4  typeGeneration: true,
5});

(examples/node-app/src/main.ts:44-49)

Configuration Parameters:

Runtime-Specific Ports

The example applications use different ports per runtime for development convenience:

• Node.js: Port 8080 (examples/node-app/src/main.ts:46)
• Bun: Port 8081 (examples/bun-app/src/main.ts:46)
• Deno: Port 8082 (examples/deno-app/src/main.ts:46)
• Documentation examples: Port 1366 (examples/document/01-simplest.ts:11)

Testing with Playground

Access the playground interface at http://localhost:{port}/playground to interactively test registered actions. The playground provides:

• Schema exploration
• Query builder with autocomplete
• Response visualization
• Request history

(README.md:289)

Testing with HTTP Client

Send POST requests to http://localhost:{port}/lesan with JSON payload containing service, model, action, and details:

json
1{
2  "service": "main",
3  "model": "country",
4  "act": "addCountry",
5  "details": {
6    "set": {
7      "name": "Iran",
8      "population": 85000000,
9      "abb": "IR"
10    },
11    "get": {
12      "_id": 1,
13      "name": 1,
14      "population": 1
15    }
16  }
17}

(README.md:294-303)

Common Issues and Troubleshooting

Issue 1: MongoDB Connection Refused

Symptoms: Application fails to start with connection error to MongoDB.

Cause: MongoDB service is not running or connection string is incorrect.

Solution:

1. Verify MongoDB service status: mongod --version or brew services list (macOS)
2. Start MongoDB service: mongod or brew services start mongodb-community
3. Confirm connection string matches your MongoDB configuration
4. Check firewall settings for port 27017

Evidence: All examples use mongodb://127.0.0.1:27017/ as the default connection string (examples/node-app/src/main.ts:8).

Issue 2: Port Already in Use

Symptoms: Server fails to start with "EADDRINUSE" error.

Cause: Another process is using the specified port.

Solution:

1. Identify the process: lsof -i :1366 (Unix/macOS) or netstat -ano | findstr :1366 (Windows)
2. Terminate the conflicting process or change the port in runServer configuration
3. Use different ports for multiple instances (8080, 8081, 8082 as shown in examples)

Evidence: Example applications demonstrate port configuration flexibility (examples/node-app/src/main.ts:46).

Issue 3: Deno Permission Denied

Symptoms: Deno execution fails with permission errors.

Cause: Deno requires explicit permissions for network and file system access.

Solution: Use the -A flag to grant all permissions:

bash
1deno run -A main.ts

Alternatively, grant specific permissions:

bash
1deno run --allow-net --allow-read --allow-env main.ts

Evidence: The README specifies -A flag for Deno execution (README.md:276).

Issue 4: Module Not Found in Node.js

Symptoms: TypeScript execution fails with module resolution errors.

Cause: Missing tsx or TypeScript execution environment.

Solution:

1. Install tsx globally: npm install -g tsx
2. Or use npx: npx tsx main.ts
3. Ensure type: "module" is set in package.json for ES modules

Evidence: Node.js execution requires tsx or similar TypeScript runner (README.md:261-265).

Issue 5: Playground Not Accessible

Symptoms: Server starts but playground URL returns 404.

Cause: Playground option not enabled in server configuration.

Solution: Ensure playground: true is set in the runServer options:

typescript
1coreApp.runServer({ 
2  port: 1366, 
3  typeGeneration: false, 
4  playground: true  // Must be explicitly enabled
5});

Evidence: All example implementations explicitly set playground: true (examples/document/01-simplest.ts:11).

Next Steps

After successfully running the minimal server, explore these advanced features:

Data Modeling Deep Dive: Learn about model relationships, embedded documents, and reference handling in the Structures documentation.

Advanced Query Operations: Implement complex queries with filtering, pagination, and sorting using the ODM layer. Refer to examples like findOne and deleteOne operations (examples/document/06-1-find-one.ts:464-489, examples/document/09-1-deleteOne.ts:718-742).

Performance Optimization: Understand Lesan's benchmark results and optimization strategies in the Advanced Guide.

API Reference: Explore the complete API documentation at API Reference for detailed function signatures and usage patterns.

Type Generation: Enable typeGeneration: true in server configuration to automatically generate TypeScript types from your schemas for enhanced IDE support and type safety.