Skip to main content

Introduction

Welcome to Lesan — a blazing-fast, cross-platform web framework and ODM for building modern APIs with MongoDB.

What is Lesan?​

Lesan is a new way to build web servers and NoSQL data models. It combines the flexibility of GraphQL with the performance of direct MongoDB queries, all while maintaining complete end-to-end type safety.

Key Features​

  • Client-Driven Projections — Fetch exactly the data you need, nothing more
  • Automatic Bi-Directional Relations — Define once, get both sides for free
  • End-to-End TypeScript Safety — Types generated from your actual code
  • Cross-Platform — Runs on Node.js, Bun, and Deno
  • Extreme Performance — Much faster than traditional ORMs or GraphQL
  • MongoDB Native — Full compatibility with MongoDB's powerful query language

Quick Start​

Installation​

# Node.js
npm install @hemedani/lesan mongodb superstruct

# Bun
bun add @hemedani/lesan mongodb superstruct

# Deno
import { lesan } from "jsr:@hemedani/lesan";

Create Your First API​

import { lesan, MongoClient, string, number, object, ObjectId } from "@hemedani/lesan";

// 1. Initialize
const coreApp = lesan();

// 2. Connect to MongoDB
const client = await new MongoClient("mongodb://localhost:27017/").connect();
coreApp.odm.setDb(client.db("myapp"));

// 3. Define a model
const countries = coreApp.odm.newModel("country", {
  name: string(),
  population: number(),
}, {});

// 4. Define an action
const addCountry = async (body) => {
  return await countries.insertOne({
    doc: body.details.set,
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "country",
  actName: "addCountry",
  validator: object({
    set: object({ name: string(), population: number() }),
    get: object(),
  }),
  fn: addCountry,
});

// 5. Start the server
await coreApp.runServer({
  port: 8000,
  playground: true,
  typeGeneration: true,
});

Test Your API​

curl -X POST http://localhost:8000/lesan \
  -H "Content-Type: application/json" \
  -d '{
    "model": "country",
    "act": "addCountry",
    "details": {
      "set": { "name": "Iran", "population": 85000000 },
      "get": { "name": 1, "population": 1 }
    }
  }'

Or open http://localhost:8000/playground to use the interactive API explorer.

Documentation Structure​

SectionDescription
API ReferenceComplete API documentation
Server APIServer setup, actions, context
Models & ODMSchemas, relations, CRUD operations
Queries & ProjectionsClient-driven projections and aggregation
Type SystemTypeScript types and generated code
Cross-PlatformNode.js, Bun, and Deno support

Why Lesan?​

vs Traditional REST​

FeatureRESTLesan
Over-fetchingCommonEliminated
Under-fetchingCommonEliminated
Endpoint countManyOne
Type safetyManualAutomatic
RelationsManual joinsAutomatic

vs GraphQL​

FeatureGraphQLLesan
FlexibilityHighHigh
PerformanceResolver overheadDirect MongoDB
ComplexityHighLow
Type safetySchema-firstCode-first
MongoDBNeeds wrapperNative

vs Traditional ORMs​

FeatureORMsLesan
RelationsForeign keysEmbedded (denormalized)
QueriesAbstractedNative MongoDB
ProjectionsLimitedClient-driven
PerformanceGoodExcellent

Built with Lesan​

Lesan is already powering real production applications. Here's a showcase of what can be built with it.

ZiWound — War Crimes Documentation Platform​

ziwound.com is a full-stack war crimes documentation system built entirely with Lesan. It's a serious, production-grade application that demonstrates Lesan's capabilities at scale. ZiWound is open source — you can read the entire codebase on github.com/hemedani/ziwound and study the real models, acts, and utilities end-to-end.

Backend (Deno + Lesan + MongoDB):

  • 15 data models — user, report, document, file, country, province, city, category, tag, blogPost, warCriminal, confirmation, and more
  • 98 actions (acts) — the entire API is expressed as acts, with per-act validators handling input (set) and client-driven projections (get)
  • Rich relation graph — reports link to reporters, documents, tags, categories, hostile countries, and locations, with Lesan automatically embedding and syncing the reverse relations (e.g. each user keeps a sorted, limited list of their reports)
  • GeoJSON support — native MongoDB geospatial queries for interactive map-based exploration (MapLibre GL + Leaflet)
  • JWT auth & RBAC — role-based access control (Ghost, Manager, Editor, Ordinary) built on the request context + preValidation/preAct hooks
  • Production deployment — Dockerized, with CORS config, static file serving, rate limiting, and generated TypeScript declarations (typeGeneration: true)

Frontend (Next.js):

  • Nine languages with full RTL/LTR layout flipping (Persian, English, Arabic, Chinese, Portuguese, Spanish, Dutch, Turkish, Russian)
  • Secure multi-language report submission with file attachments, location, and metadata
  • Advanced search and filtering of documented incidents, a blog section, and a comprehensive admin panel
  • PWA support and server actions for type-safe backend communication

The whole stack — data modeling, relations, validation, and the client-server contract — is driven by Lesan's generated types, proving that Lesan scales from a quick prototype to a multi-language production platform.

Next Steps​

Community​