This page is generated from the following source files:
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).
Before installing Lesan, ensure the following requirements are met:
Runtime Environment:
Database:
Development Tools (Node.js only):
tsx or ts-node for TypeScript executionThe 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).
Lesan provides platform-specific installation methods for each supported runtime. The framework requires both the lesan package and the mongodb driver as dependencies.
bash1npm install lesan mongodb
bash1bun add lesan mongodb
Deno uses direct imports without a package installation step. Import the framework using the npm: specifier in the source file:
typescript1import { lesan } from "npm:lesan"; 2import { MongoClient } from "npm:mongodb";
(README.md:61-64, examples/deno-app/src/main.ts:1-2)
| Runtime | Package Manager | Dependencies | Import Style |
|---|---|---|---|
| Node.js | npm/yarn/pnpm | lesan mongodb | Standard ES modules |
| Bun | bun | lesan mongodb | Standard ES modules |
| Deno | None (imports only) | N/A | npm: specifier |
The fastest path to a running Lesan application involves three core steps: initializing the application instance, connecting to MongoDB, and starting the HTTP server.
Create a file named main.ts with the following minimal configuration:
typescript1import { 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)
Execute the application using the runtime-specific command:
Node.js:
bash1npx tsx main.ts
Bun:
bash1bun run main.ts
Deno:
bash1deno run -A main.ts
Upon successful startup, the terminal displays the following output:
bash1HTTP 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/
The server exposes two primary endpoints:
http://localhost:1366/lesan (POST requests for data operations)http://localhost:1366/playground (interactive query builder and tester)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.
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.
typescript1const 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)
Actions combine validation logic with business operations. Each action requires:
typescript1const 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)
A more comprehensive example demonstrates model relationships and complete action lifecycle:
typescript1const 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)
The runServer function accepts configuration parameters for port, playground access, and type generation:
typescript1app.runServer({ 2 port: 8080, 3 playground: true, 4 typeGeneration: true, 5});
(examples/node-app/src/main.ts:44-49)
Configuration Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
port | number | Required | HTTP server listening port |
playground | boolean | false | Enable interactive playground UI |
typeGeneration | boolean | false | Generate TypeScript types from schemas |
The example applications use different ports per runtime for development convenience:
Access the playground interface at http://localhost:{port}/playground to interactively test registered actions. The playground provides:
Send POST requests to http://localhost:{port}/lesan with JSON payload containing service, model, action, and details:
json1{ 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}
Symptoms: Application fails to start with connection error to MongoDB.
Cause: MongoDB service is not running or connection string is incorrect.
Solution:
mongod --version or brew services list (macOS)mongod or brew services start mongodb-communityEvidence: All examples use mongodb://127.0.0.1:27017/ as the default connection string (examples/node-app/src/main.ts:8).
Symptoms: Server fails to start with "EADDRINUSE" error.
Cause: Another process is using the specified port.
Solution:
lsof -i :1366 (Unix/macOS) or netstat -ano | findstr :1366 (Windows)runServer configurationEvidence: Example applications demonstrate port configuration flexibility (examples/node-app/src/main.ts:46).
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:
bash1deno run -A main.ts
Alternatively, grant specific permissions:
bash1deno run --allow-net --allow-read --allow-env main.ts
Evidence: The README specifies -A flag for Deno execution (README.md:276).
Symptoms: TypeScript execution fails with module resolution errors.
Cause: Missing tsx or TypeScript execution environment.
Solution:
npm install -g tsxnpx tsx main.tstype: "module" is set in package.json for ES modulesEvidence: Node.js execution requires tsx or similar TypeScript runner (README.md:261-265).
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:
typescript1coreApp.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).
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.