This page is generated from the following source files:
The Lesan framework originates from a critical analysis of modern web development paradigms, specifically addressing the friction between performance and complexity in large-scale applications. While NoSQL databases offer exceptional speed, their inherent complexity often becomes a significant burden in enterprise environments. Conversely, GraphQL provides excellent client-server connectivity capabilities but introduces additional layers of complexity and specific weaknesses that can hinder project velocity (README.md:5-9).
Lesan positions itself as a solution that bridges this gap, aiming to provide the raw performance of NoSQL with a structured, simplified approach to data management. The framework's design philosophy emphasizes "write once, run anywhere" capability, natively supporting major JavaScript runtimes—Node.js, Bun, and Deno—without requiring configuration overhead (README.md:9-9).
Performance metrics indicate that this architectural approach yields substantial results. Benchmarks demonstrate that Lesan returns data significantly faster than traditional stacks; for instance, it is reported to be 1168% faster than Prisma-express-REST (Postgres) and 1417% faster than Prisma-express-GraphQL (Postgres). In more extreme comparisons against Mongoose-express-REST with sorting, the performance differential reaches 298971% (README.md:22-29). These figures suggest a focus on optimizing the data retrieval and execution pipeline to minimize latency.
Lesan's architecture is fundamentally designed for cross-platform compatibility, allowing a single codebase to operate across different JavaScript runtimes. This is achieved through a unified module export strategy and runtime-specific entry points defined in the package configuration.
The package.json file reveals a sophisticated export map that directs different runtimes to specific entry points. For Deno, the entry point is explicitly mapped to ./mod.ts, while Bun and Node.js (ESM/CommonJS) utilize the compiled ./dist outputs (package.json:8-22). This abstraction ensures that developers can import the framework using standard syntax regardless of their environment.
To facilitate this interoperability, the project includes global type declarations for runtime detection. Specifically, Deno and Bun are declared as global variables to satisfy TypeScript requirements across these environments (src/global.d.ts:1-4). The Deno configuration further reinforces this by setting the main export to the root mod.ts file (deno.json:1-9).
This architecture eliminates the need for platform-specific build configurations during development, adhering to the "zero configuration" goal mentioned in the project documentation.
The structural integrity of Lesan relies on a modular composition pattern where the core application instance is composed of distinct functional responsibilities: Schemas, Actions (Acts), ODM (Object Document Mapping), and Server utilities.
The primary entry point, the lesan function, initializes these subsystems. It creates internal state objects for schemasObj and actsObj (services) and returns a unified interface containing:
src/lesan.ts:7-23).The public API surface is streamlined through the main module exports. The src/mod.ts file aggregates exports from the core logic, types, and NPM dependencies, ensuring that consumers have access to necessary types (like TLesanBody, Infer) and utilities (like ObjectId, Struct) without deep imports (src/mod.ts:1-12). The root mod.ts acts as the Deno-specific entry point, re-exporting the source module contents (mod.ts:1-1).
正在加载图表渲染器...
Diagram Explanation:
lesan function (src/lesan.ts:7-23).mongodb and superstruct) which are re-exported via src/npmDeps.ts (src/npmDeps.ts:1-195), ensuring a consistent API for database operations and validation.Context Manager acts as a state carrier, injecting headers and request bodies into the execution flow, managed by contextFns (src/lesan.ts:20-20).runServer function returned by the main factory.Lesan implements a structured request processing model that separates the "what" (data definition) from the "how" (execution logic). This is achieved through a specific request body structure and a dynamic context management system.
The TLesanBody interface defines the contract for client requests. It mandates three key properties:
set (input data) and get (projection/return fields) (src/types.ts:29-45).This structure forces a clear distinction between input validation (set) and output projection (get), allowing the framework to optimize data fetching and ensure type safety.
The LesanContenxt interface serves as a state carrier throughout the request lifecycle. It is a flexible dictionary structure that explicitly holds Headers and the parsed body, but allows for arbitrary key-value pairs to be added (e.g., user authentication data) (src/types.ts:59-63).
The context is managed by a set of functional utilities exported as contextFns:
setContext / addContext: Initializes or merges data into the context object.addReqToContext: Stores the raw Request object.addHeaderToContext: Extracts and stores HTTP Headers.addBodyToContext: Stores the parsed TLesanBody (src/context.ts:25-61).This mechanism allows downstream business logic (Acts) to access request metadata and state without tight coupling to the HTTP layer.
正在加载图表渲染器...
Sequence Explanation:
addBodyToContext and addHeaderToContext (src/context.ts:46-60).details.get property in the body dictates the projection used in the ODM layer, ensuring that only requested fields are retrieved from the database.Lesan maintains a strict dependency policy, relying on a minimal set of robust libraries to handle complex tasks like validation and database communication.
The framework explicitly depends on two major libraries:
mongodb (v6.3.0): The official MongoDB driver. It is used for all database operations, connection management, and type definitions (e.g., Document, Filter, ObjectId) (package.json:72-72).superstruct (v2.0.2): A library for struct validation and data typing. It provides the schema definition capabilities used to validate details.set in requests (package.json:73-73).To provide a seamless developer experience, Lesan re-exports the vast majority of the mongodb and superstruct APIs via src/npmDeps.ts. This includes:
object, string, number, optional, etc., from Superstruct (src/npmDeps.ts:2-56).Filter, Document, InsertOneOptions, ObjectId, etc., from MongoDB (src/npmDeps.ts:178-195).This design allows developers to import these utilities directly from the lesan package (e.g., import { object, string, ObjectId } from 'lesan'), reducing the need for multiple dependency installations and ensuring version compatibility.
| Component | Technology | Version/Details |
|---|---|---|
| Core Language | TypeScript | 5.9.3 (DevDependency) |
| Runtimes | Node.js, Bun, Deno | Cross-platform support |
| Database | MongoDB | 6.3.0 |
| Validation | Superstruct | 2.0.2 |
| Build Tool | tsup | 8.5.1 |
| Test Runners | Native (tsx/bun/deno test) | Runtime-specific adapters |
README.md:9-9).README.md:22-29).set) and output (get) in request bodies for precise data fetching and validation (src/types.ts:13-23).src/lesan.ts:15-19).src/context.ts:67-72).Services type and TLesanBody.service) fits well with microservice decompositions.To gain a comprehensive understanding of the Lesan framework, the following reading path is recommended for the technical analysis:
正在加载图表渲染器...
Reading Guide: