Registry / database / ent-framework

ent-framework

JSON →
library2.26.1jsnpmunverified

Ent Framework is a TypeScript-first library designed for interacting with PostgreSQL databases, presenting a graph-like representation of entities rather than a traditional ORM approach. It is currently stable at version 2.26.1 and appears to be actively maintained with regular updates. Key differentiators include its robust solution for the 'N+1 selects' problem through query batching and coalescing, built-in support for microsharding and intelligent replication lag tracking to optimize read operations, and a comprehensive row-level security (privacy layer) system that defines access based on entity relationships. The framework also emphasizes immutability for entity properties and offers a pluggable architecture, allowing integration into existing database setups. It aims to simplify scaling and security concerns for complex business logic by abstracting away much of the underlying SQL complexities.

npm install ent-framework
INSTALL
IMPORT
SIG · ENT-FRAMEWORK
E
ent-framework
databasejavascriptv2.26.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Ent
import { Ent } from 'ent-framework';
const Ent = require('ent-framework').Ent;
The base class for all domain entities. Extend this class to define your business objects.
EntContext
import { EntContext } from 'ent-framework';
import { Context } from 'ent-framework';
The central context object for managing database interactions, transactions, and entity lifecycle. Often initialized once per application.
Field
import { Field } from 'ent-framework';
import { Prop } from 'ent-framework';
Decorator used to define properties on an Ent class that map to database columns or relationships.

This quickstart demonstrates defining a basic 'User' Ent class, initializing the EntContext, creating a new user entity, and then loading it by ID, showcasing fundamental interaction patterns.

import { Ent, EntContext, Field, UUID, PrimaryKey, UUIDField, StringField, BooleanField, EntCreationOptions, EntQueryContext } from 'ent-framework'; interface UserData { id: UUID; name: string; isActive: boolean; } class User extends Ent<UserData> { @Field(UUIDField()) id: UUID = PrimaryKey.empty(); @Field(StringField()) name: string = ''; @Field(BooleanField({ defaultValue: true })) isActive: boolean = true; static create(context: EntQueryContext, data: Partial<UserData>, options?: EntCreationOptions): User { return super.create(context, data, options) as User; } static load(context: EntQueryContext, id: UUID): Promise<User | null> { return super.load(context, id) as Promise<User | null>; } } async function runExample() { // In a real application, DATABASE_URL would point to your PostgreSQL instance. // For this example, we simulate a context setup. const entContext = new EntContext({ // Replace with actual database connection configuration // For demonstration, we'll use a placeholder URL. connectionUri: process.env.DATABASE_URL ?? 'postgresql://user:password@host:port/database', // Other configuration like sharding rules, logging, etc. logLevel: 'debug' }); try { await entContext.init(); console.log('EntContext initialized.'); // Assume schema migration/sync is handled externally or by framework setup const newUser = await User.create(entContext, { name: 'Alice', isActive: true }); console.log(`Created user: ${newUser.name} (ID: ${newUser.id})`); const loadedUser = await User.load(entContext, newUser.id); if (loadedUser) { console.log(`Loaded user: ${loadedUser.name}, Active: ${loadedUser.isActive}`); } else { console.log('User not found.'); } // Example of another operation (e.g., updating) if (loadedUser) { const updatedUser = await loadedUser.update(entContext, { isActive: false }); console.log(`Updated user: ${updatedUser.name}, Active: ${updatedUser.isActive}`); } } catch (error) { console.error('Error during example run:', error); } finally { await entContext.close(); console.log('EntContext closed.'); } } runExample();
Debug
Known issues
breakingMajor versions of Ent Framework may introduce breaking changes to the core API or configuration schemas, particularly around how Ent classes are defined, how relationships are managed, or changes to the database abstraction layer. Always consult the release notes when upgrading.
fix
Review the changelog and migration guides for the specific version you are upgrading to. Pay close attention to changes in decorators, field types, and `EntContext` configuration options.
affects: >=2.0
gotchaEnt Framework leverages TypeScript decorators, which require `emitDecoratorMetadata` and `experimentalDecorators` to be enabled in your `tsconfig.json`. Failing to do so will result in runtime errors related to decorator usage.
fix
Ensure `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` are set under `compilerOptions` in your `tsconfig.json`.
affects: >=1.0
gotchaWhile Ent Framework handles query batching and N+1 problems automatically, improper use of raw SQL or bypassing the framework's loading mechanisms can reintroduce performance bottlenecks and negate the benefits of its optimized query patterns.
fix
Always use the provided `EntContext` and `Ent` methods for data retrieval and manipulation. Understand the framework's intended data access patterns to ensure optimal performance.
affects: >=1.0
gotchaSchema synchronization and migration are critical for any database framework. Ent Framework often requires careful management of your database schema to match your Ent definitions. Automatic migrations might not cover all edge cases or production scenarios.
fix
Implement a robust schema migration strategy (e.g., using a separate migration tool or the framework's recommended approach if available) and test thoroughly in non-production environments before deploying schema changes.
affects: >=1.0
gotchaCorrectly configuring microsharding and replication lag tracking can be complex. Misconfigurations can lead to data consistency issues (e.g., reading stale data from replicas) or routing requests to incorrect shards, causing data not found errors or performance degradation.
fix
Thoroughly understand the sharding key definitions, replica lag tolerances, and routing logic. Implement comprehensive integration tests to validate data consistency and correct routing across your sharded and replicated database cluster.
affects: >=1.0
Errors
Common errors & fixes
TypeError: Reflect.metadata is not a function
TypeScript decorators metadata emission is disabled in `tsconfig.json`.
fix
Add or ensure `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` are in `compilerOptions` in `tsconfig.json`.
Error: connect ECONNREFUSED <DB_HOST>:<DB_PORT>
The application cannot connect to the PostgreSQL database. This could be due to incorrect connection URI, database server not running, firewall issues, or incorrect credentials.
fix
Verify the `connectionUri` in `EntContext` initialization. Ensure the PostgreSQL server is running, accessible from the application's host, and that firewall rules permit the connection. Check user credentials and database existence.
Error: relation "<table_name>" does not exist
The database schema does not match the defined Ent classes. This usually happens when an Ent class is defined but the corresponding table or column does not exist in the database, or schema migrations have not been applied.
fix
Run database migrations to create or update the tables and columns corresponding to your Ent definitions. Ensure your Ent class names correctly map to table names (considering potential naming conventions).
Upgrade
Version history
2.26.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources