Ent Framework

Common errors

• TypeError: Reflect.metadata is not a function

  cause 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>

  cause 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

  cause 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).

Warnings

• breaking Major 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.
• gotcha Ent 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`.
• gotcha While 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.
• gotcha Schema 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.
• gotcha Correctly 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.

Install

• npm install ent-framework npm
• yarn add ent-framework yarn
• pnpm add ent-framework pnpm

Imports

• Ent
  wrong:

  const Ent = require('ent-framework').Ent;

  correct:

  import { Ent } from 'ent-framework';

  The base class for all domain entities. Extend this class to define your business objects.
• EntContext
  wrong:

  import { Context } from 'ent-framework';

  correct:

  import { EntContext } from 'ent-framework';

  The central context object for managing database interactions, transactions, and entity lifecycle. Often initialized once per application.
• Field
  wrong:

  import { Prop } from 'ent-framework';

  correct:

  import { Field } from 'ent-framework';

  Decorator used to define properties on an Ent class that map to database columns or relationships.

Quickstart

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();