metal-orm 1.0.59 → 1.0.62

package/dist/index.cjs

@@ -47,7 +47,9 @@ __export(index_exports, {
   BelongsTo: () => BelongsTo,
   BelongsToMany: () => BelongsToMany,
   Column: () => Column,
+  ConstructorMaterializationStrategy: () => ConstructorMaterializationStrategy,
   DefaultBelongsToReference: () => DefaultBelongsToReference,
+  DefaultEntityMaterializer: () => DefaultEntityMaterializer,
   DefaultHasManyCollection: () => DefaultHasManyCollection,
   DefaultManyToManyCollection: () => DefaultManyToManyCollection,
   DeleteQueryBuilder: () => DeleteQueryBuilder,
@@ -63,6 +65,7 @@ __export(index_exports, {
   Pool: () => Pool,
   PostgresDialect: () => PostgresDialect,
   PrimaryKey: () => PrimaryKey,
+  PrototypeMaterializationStrategy: () => PrototypeMaterializationStrategy,
   RelationKinds: () => RelationKinds,
   STANDARD_COLUMN_TYPES: () => STANDARD_COLUMN_TYPES,
   SelectQueryBuilder: () => SelectQueryBuilder,
@@ -134,6 +137,7 @@ __export(index_exports, {
   dayOfWeek: () => dayOfWeek,
   defineTable: () => defineTable,
   degrees: () => degrees,
+  deleteFrom: () => deleteFrom,
   denseRank: () => denseRank,
   diffSchema: () => diffSchema,
   div: () => div,
@@ -170,6 +174,7 @@ __export(index_exports, {
   inList: () => inList,
   inSubquery: () => inSubquery,
   initcap: () => initcap,
+  insertInto: () => insertInto,
   instr: () => instr,
   introspectSchema: () => introspectSchema,
   isCaseExpressionNode: () => isCaseExpressionNode,
@@ -212,6 +217,7 @@ __export(index_exports, {
   lt: () => lt,
   lte: () => lte,
   ltrim: () => ltrim,
+  materializeAs: () => materializeAs,
   max: () => max,
   md5: () => md5,
   min: () => min,
@@ -258,6 +264,7 @@ __export(index_exports, {
   rtrim: () => rtrim,
   second: () => second,
   sel: () => sel,
+  selectFrom: () => selectFrom,
   selectFromEntity: () => selectFromEntity,
   setRelations: () => setRelations,
   sha1: () => sha1,
@@ -281,6 +288,7 @@ __export(index_exports, {
   trunc: () => trunc,
   truncate: () => truncate,
   unixTimestamp: () => unixTimestamp,
+  update: () => update,
   upper: () => upper,
   utcNow: () => utcNow,
   valueToOperand: () => valueToOperand,
@@ -6234,6 +6242,132 @@ var loadLazyRelationsForTable = async (ctx, table, lazyRelations, lazyRelationOp
   }
 };
 
+// src/orm/entity-metadata.ts
+var metadataMap = /* @__PURE__ */ new Map();
+var ensureEntityMetadata = (target) => {
+  let meta = metadataMap.get(target);
+  if (!meta) {
+    meta = {
+      target,
+      tableName: target.name || "unknown",
+      columns: {},
+      relations: {}
+    };
+    metadataMap.set(target, meta);
+  }
+  return meta;
+};
+var getEntityMetadata = (target) => {
+  return metadataMap.get(target);
+};
+var getAllEntityMetadata = () => {
+  return Array.from(metadataMap.values());
+};
+var addColumnMetadata = (target, propertyKey, column) => {
+  const meta = ensureEntityMetadata(target);
+  meta.columns[propertyKey] = { ...column };
+};
+var addRelationMetadata = (target, propertyKey, relation) => {
+  const meta = ensureEntityMetadata(target);
+  meta.relations[propertyKey] = relation;
+};
+var setEntityTableName = (target, tableName, hooks) => {
+  const meta = ensureEntityMetadata(target);
+  if (tableName && tableName.length > 0) {
+    meta.tableName = tableName;
+  }
+  if (hooks) {
+    meta.hooks = hooks;
+  }
+};
+var buildTableDef = (meta) => {
+  if (meta.table) {
+    return meta.table;
+  }
+  const columns = {};
+  for (const [key, def] of Object.entries(meta.columns)) {
+    columns[key] = {
+      ...def,
+      name: key,
+      table: meta.tableName
+    };
+  }
+  const table = defineTable(meta.tableName, columns, {}, meta.hooks);
+  meta.table = table;
+  return table;
+};
+
+// src/orm/entity-registry.ts
+var tableToConstructor = /* @__PURE__ */ new Map();
+var rebuildRegistry = () => {
+  tableToConstructor.clear();
+  for (const meta of getAllEntityMetadata()) {
+    if (meta.table) {
+      tableToConstructor.set(meta.table, meta.target);
+    }
+  }
+};
+
+// src/orm/entity-materializer.ts
+var PrototypeMaterializationStrategy = class {
+  materialize(ctor, data) {
+    const instance = Object.create(ctor.prototype);
+    Object.assign(instance, data);
+    return instance;
+  }
+};
+var ConstructorMaterializationStrategy = class {
+  materialize(ctor, data) {
+    const instance = Reflect.construct(ctor, []);
+    Object.assign(instance, data);
+    return instance;
+  }
+};
+var DefaultEntityMaterializer = class {
+  constructor(strategy = new ConstructorMaterializationStrategy()) {
+    this.strategy = strategy;
+  }
+  materialize(ctor, row) {
+    const instance = this.strategy.materialize(ctor, row);
+    this.materializeRelations(instance, ctor);
+    return instance;
+  }
+  materializeMany(ctor, rows) {
+    return rows.map((row) => this.materialize(ctor, row));
+  }
+  /**
+   * Recursively materializes nested relation data.
+   */
+  materializeRelations(instance, _ctor) {
+    rebuildRegistry();
+    for (const [key, value] of Object.entries(instance)) {
+      if (value === null || value === void 0) continue;
+      if (typeof value === "object" && !Array.isArray(value)) {
+        const nested = value;
+        if (this.isEntityLike(nested)) {
+        }
+      }
+      if (Array.isArray(value) && value.length > 0) {
+        const first = value[0];
+        if (typeof first === "object" && first !== null && this.isEntityLike(first)) {
+        }
+      }
+    }
+  }
+  /**
+   * Simple heuristic to check if an object looks like an entity.
+   */
+  isEntityLike(obj) {
+    return "id" in obj || Object.keys(obj).some(
+      (k) => k.endsWith("Id") || k === "createdAt" || k === "updatedAt"
+    );
+  }
+};
+var materializeAs = (ctor, results) => {
+  const materializer = new DefaultEntityMaterializer();
+  return materializer.materializeMany(ctor, results);
+};
+
 // src/query-builder/query-resolution.ts
 function resolveSelectQuery(query) {
   const candidate = query;
@@ -6644,6 +6778,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   relationFacet;
   lazyRelations;
   lazyRelationOptions;
+  entityConstructor;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -6651,7 +6786,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions) {
+  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions, entityConstructor) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
     const createAstService = (nextState) => deps.createQueryAstService(table, nextState);
@@ -6663,6 +6798,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     };
     this.lazyRelations = new Set(lazyRelations ?? []);
     this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
+    this.entityConstructor = entityConstructor;
     this.columnSelector = deps.createColumnSelector(this.env);
     const relationManager = deps.createRelationManager(this.env);
     this.fromFacet = new SelectFromFacet(this.env, createAstService);
@@ -6686,12 +6822,15 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       context.hydration,
       this.env.deps,
       lazyRelations,
-      lazyRelationOptions
+      lazyRelationOptions,
+      this.entityConstructor
     );
   }
   /**
    * Applies an alias to the root FROM table.
    * @param alias - Alias to apply
+   * @example
+   * const qb = new SelectQueryBuilder(userTable).as('u');
    */
   as(alias) {
     const nextContext = this.fromFacet.as(this.context, alias);
@@ -6749,6 +6888,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Selects raw column expressions
    * @param cols - Column expressions as strings
    * @returns New query builder instance with raw column selections
+   * @example
+   * qb.selectRaw('COUNT(*) as total', 'UPPER(name) as upper_name');
    */
   selectRaw(...cols) {
     return this.clone(this.projectionFacet.selectRaw(this.context, cols));
@@ -6759,6 +6900,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param query - Query builder or query node for the CTE
    * @param columns - Optional column names for the CTE
    * @returns New query builder instance with the CTE
+   * @example
+   * const recentUsers = new SelectQueryBuilder(userTable)
+   *   .where(gt(userTable.columns.createdAt, subDays(now(), 30)));
+   * const qb = new SelectQueryBuilder(userTable)
+   *   .with('recent_users', recentUsers)
+   *   .from('recent_users');
    */
   with(name, query, columns) {
     const subAst = resolveSelectQuery(query);
@@ -6771,6 +6918,19 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param query - Query builder or query node for the CTE
    * @param columns - Optional column names for the CTE
    * @returns New query builder instance with the recursive CTE
+   * @example
+   * // Base case: select root nodes
+   * const baseQuery = new SelectQueryBuilder(orgTable)
+   *   .where(eq(orgTable.columns.parentId, 1));
+   * // Recursive case: join with the CTE itself
+   * const recursiveQuery = new SelectQueryBuilder(orgTable)
+   *   .join('org_hierarchy', 'oh', eq(orgTable.columns.parentId, col('oh.id')));
+   * // Combine base and recursive parts
+   * const orgHierarchy = baseQuery.union(recursiveQuery);
+   * // Use in main query
+   * const qb = new SelectQueryBuilder(orgTable)
+   *   .withRecursive('org_hierarchy', orgHierarchy)
+   *   .from('org_hierarchy');
    */
   withRecursive(name, query, columns) {
     const subAst = resolveSelectQuery(query);
@@ -6783,6 +6943,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param alias - Alias for the derived table
    * @param columnAliases - Optional column alias list
    * @returns New query builder instance with updated FROM
+   * @example
+   * const subquery = new SelectQueryBuilder(userTable)
+   *   .select('id', 'name')
+   *   .where(gt(userTable.columns.score, 100));
+   * qb.fromSubquery(subquery, 'high_scorers', ['userId', 'userName']);
    */
   fromSubquery(subquery, alias, columnAliases) {
     const subAst = resolveSelectQuery(subquery);
@@ -6795,6 +6960,13 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param args - Optional function arguments
    * @param alias - Optional alias for the function table
    * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
+   * @example
+   * qb.fromFunctionTable(
+   *   'generate_series',
+   *   [literal(1), literal(10), literal(1)],
+   *   'series',
+   *   { columnAliases: ['value'] }
+   * );
    */
   fromFunctionTable(name, args = [], alias, options) {
     const nextContext = this.fromFacet.fromFunctionTable(this.context, name, args, alias, options);
@@ -6805,6 +6977,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param alias - Alias for the subquery column
    * @param sub - Query builder or query node for the subquery
    * @returns New query builder instance with the subquery selection
+   * @example
+   * const postCount = new SelectQueryBuilder(postTable)
+   *   .select(count(postTable.columns.id))
+   *   .where(eq(postTable.columns.userId, col('u.id')));
+   * qb.select('id', 'name')
+   *   .selectSubquery('postCount', postCount);
    */
   selectSubquery(alias, sub2) {
     const query = resolveSelectQuery(sub2);
@@ -6818,6 +6996,15 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param joinKind - Join kind (defaults to INNER)
    * @param columnAliases - Optional column alias list for the derived table
    * @returns New query builder instance with the derived-table join
+   * @example
+   * const activeUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, true));
+   * qb.joinSubquery(
+   *   activeUsers,
+   *   'au',
+   *   eq(col('t.userId'), col('au.id')),
+   *   JOIN_KINDS.LEFT
+   * );
    */
   joinSubquery(subquery, alias, condition, joinKind = JOIN_KINDS.INNER, columnAliases) {
     const subAst = resolveSelectQuery(subquery);
@@ -6832,6 +7019,15 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param condition - Join condition expression
    * @param joinKind - Kind of join (defaults to INNER)
    * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
+   * @example
+   * qb.joinFunctionTable(
+   *   'generate_series',
+   *   [literal(1), literal(10)],
+   *   'gs',
+   *   eq(col('t.value'), col('gs.value')),
+   *   JOIN_KINDS.INNER,
+   *   { columnAliases: ['value'] }
+   * );
    */
   joinFunctionTable(name, args = [], alias, condition, joinKind = JOIN_KINDS.INNER, options) {
     const nextContext = this.joinFacet.joinFunctionTable(this.context, name, args, alias, condition, joinKind, options);
@@ -6842,6 +7038,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param table - Table to join
    * @param condition - Join condition expression
    * @returns New query builder instance with the INNER JOIN
+   * @example
+   * qb.innerJoin(
+   *   postTable,
+   *   eq(userTable.columns.id, postTable.columns.userId)
+   * );
    */
   innerJoin(table, condition) {
     const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.INNER);
@@ -6852,6 +7053,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param table - Table to join
    * @param condition - Join condition expression
    * @returns New query builder instance with the LEFT JOIN
+   * @example
+   * qb.leftJoin(
+   *   postTable,
+   *   eq(userTable.columns.id, postTable.columns.userId)
+   * );
    */
   leftJoin(table, condition) {
     const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.LEFT);
@@ -6862,6 +7068,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param table - Table to join
    * @param condition - Join condition expression
    * @returns New query builder instance with the RIGHT JOIN
+   * @example
+   * qb.rightJoin(
+   *   postTable,
+   *   eq(userTable.columns.id, postTable.columns.userId)
+   * );
    */
   rightJoin(table, condition) {
     const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.RIGHT);
@@ -6872,6 +7083,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param relationName - Name of the relationship to match
    * @param predicate - Optional predicate expression
    * @returns New query builder instance with the relationship match
+   * @example
+   * qb.match('posts', eq(postTable.columns.published, true));
    */
   match(relationName, predicate) {
     const nextContext = this.relationFacet.match(this.context, relationName, predicate);
@@ -6883,6 +7096,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param joinKind - Type of join (defaults to INNER)
    * @param extraCondition - Optional additional join condition
    * @returns New query builder instance with the relationship join
+   * @example
+   * qb.joinRelation('posts', JOIN_KINDS.LEFT);
+   * @example
+   * qb.joinRelation('posts', JOIN_KINDS.INNER, eq(postTable.columns.published, true));
    */
   joinRelation(relationName, joinKind = JOIN_KINDS.INNER, extraCondition) {
     const nextContext = this.relationFacet.joinRelation(this.context, relationName, joinKind, extraCondition);
@@ -6893,6 +7110,15 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param relationName - Name of the relationship to include
    * @param options - Optional include options
    * @returns New query builder instance with the relationship inclusion
+   * @example
+   * qb.include('posts');
+   * @example
+   * qb.include('posts', { columns: ['id', 'title', 'published'] });
+   * @example
+   * qb.include('posts', {
+   *   columns: ['id', 'title'],
+   *   where: eq(postTable.columns.published, true)
+   * });
    */
   include(relationName, options) {
     const nextContext = this.relationFacet.include(this.context, relationName, options);
@@ -6903,6 +7129,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param relationName - Name of the relation to include lazily
    * @param options - Optional include options for lazy loading
    * @returns New query builder instance with lazy relation inclusion
+   * @example
+   * const qb = new SelectQueryBuilder(userTable).includeLazy('posts');
+   * const users = await qb.execute(session);
+   * // Access posts later - they will be loaded on demand
+   * const posts = await users[0].posts;
    */
   includeLazy(relationName, options) {
     let nextContext = this.context;
@@ -6932,6 +7163,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   }
   /**
    * Convenience alias for including only specific columns from a relation.
+   * @example
+   * qb.includePick('posts', ['id', 'title', 'createdAt']);
    */
   includePick(relationName, cols) {
     const options = { columns: cols };
@@ -6941,6 +7174,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Selects columns for the root table and relations from an array of entries
    * @param config - Configuration array for deep column selection
    * @returns New query builder instance with deep column selections
+   * @example
+   * qb.selectColumnsDeep([
+   *   { type: 'root', columns: ['id', 'name'] },
+   *   { type: 'relation', relationName: 'posts', columns: ['id', 'title'] }
+   * ]);
    */
   selectColumnsDeep(config) {
     let currBuilder = this;
@@ -6976,12 +7214,67 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.env.table;
   }
   /**
-   * Executes the query and returns hydrated results
+   * Ensures that if no columns are selected, all columns from the table are selected by default.
+   */
+  ensureDefaultSelection() {
+    const columns = this.context.state.ast.columns;
+    if (!columns || columns.length === 0) {
+      return this.select(...Object.keys(this.env.table.columns));
+    }
+    return this;
+  }
+  /**
+   * Executes the query and returns hydrated results.
+   * If the builder was created with an entity constructor (e.g. via selectFromEntity),
+   * this will automatically return fully materialized entity instances.
+   *
    * @param ctx - ORM session context
-   * @returns Promise of entity instances
+   * @returns Promise of entity instances (or objects if generic T is not an entity)
+   * @example
+   * const users = await selectFromEntity(User).execute(session);
+   * // users is User[]
+   * users[0] instanceof User; // true
    */
   async execute(ctx) {
-    return executeHydrated(ctx, this);
+    if (this.entityConstructor) {
+      return this.executeAs(this.entityConstructor, ctx);
+    }
+    const builder = this.ensureDefaultSelection();
+    return executeHydrated(ctx, builder);
+  }
+  /**
+   * Executes the query and returns plain row objects (POJOs), ignoring any entity materialization.
+   * Use this if you want raw data even when using selectFromEntity.
+   *
+   * @param ctx - ORM session context
+   * @returns Promise of plain entity instances
+   * @example
+   * const rows = await selectFromEntity(User).executePlain(session);
+   * // rows is EntityInstance<UserTable>[] (plain objects)
+   * rows[0] instanceof User; // false
+   */
+  async executePlain(ctx) {
+    const builder = this.ensureDefaultSelection();
+    return executeHydrated(ctx, builder);
+  }
+  /**
+   * Executes the query and returns results as real class instances.
+   * Unlike execute(), this returns actual instances of the decorated entity class
+   * with working methods and proper instanceof checks.
+   * @param entityClass - The entity class constructor
+   * @param ctx - ORM session context
+   * @returns Promise of entity class instances
+   * @example
+   * const users = await selectFromEntity(User)
+   *   .include('posts')
+   *   .executeAs(User, session);
+   * users[0] instanceof User; // true!
+   * users[0].getFullName();   // works!
+   */
+  async executeAs(entityClass, ctx) {
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydrated(ctx, builder);
+    return materializeAs(entityClass, results);
   }
   /**
    * Executes a count query for the current builder without LIMIT/OFFSET clauses.
@@ -6999,21 +7292,38 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const { items, totalItems } = await qb.executePaged(session, { page: 1, pageSize: 20 });
    */
   async executePaged(session, options) {
-    return executePagedQuery(this, session, options, (sess) => this.count(sess));
+    const builder = this.ensureDefaultSelection();
+    return executePagedQuery(builder, session, options, (sess) => this.count(sess));
   }
   /**
    * Executes the query with provided execution and hydration contexts
    * @param execCtx - Execution context
    * @param hydCtx - Hydration context
    * @returns Promise of entity instances
+   * @example
+   * const execCtx = new ExecutionContext(session);
+   * const hydCtx = new HydrationContext();
+   * const users = await qb.executeWithContexts(execCtx, hydCtx);
    */
   async executeWithContexts(execCtx, hydCtx) {
-    return executeHydratedWithContexts(execCtx, hydCtx, this);
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydratedWithContexts(execCtx, hydCtx, builder);
+    if (this.entityConstructor) {
+      return materializeAs(this.entityConstructor, results);
+    }
+    return results;
   }
   /**
    * Adds a WHERE condition to the query
    * @param expr - Expression for the WHERE clause
    * @returns New query builder instance with the WHERE condition
+   * @example
+   * qb.where(eq(userTable.columns.id, 1));
+   * @example
+   * qb.where(and(
+   *   eq(userTable.columns.active, true),
+   *   gt(userTable.columns.createdAt, subDays(now(), 30))
+   * ));
    */
   where(expr) {
     const nextContext = this.predicateFacet.where(this.context, expr);
@@ -7023,6 +7333,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Adds a GROUP BY clause to the query
    * @param term - Column definition or ordering term to group by
    * @returns New query builder instance with the GROUP BY clause
+   * @example
+   * qb.select('departmentId', count(userTable.columns.id))
+   *   .groupBy(userTable.columns.departmentId);
    */
   groupBy(term) {
     const nextContext = this.predicateFacet.groupBy(this.context, term);
@@ -7032,6 +7345,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Adds a HAVING condition to the query
    * @param expr - Expression for the HAVING clause
    * @returns New query builder instance with the HAVING condition
+   * @example
+   * qb.select('departmentId', count(userTable.columns.id))
+   *   .groupBy(userTable.columns.departmentId)
+   *   .having(gt(count(userTable.columns.id), 5));
    */
   having(expr) {
     const nextContext = this.predicateFacet.having(this.context, expr);
@@ -7054,6 +7371,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Adds a DISTINCT clause to the query
    * @param cols - Columns to make distinct
    * @returns New query builder instance with the DISTINCT clause
+   * @example
+   * qb.distinct(userTable.columns.email);
+   * @example
+   * qb.distinct(userTable.columns.firstName, userTable.columns.lastName);
    */
   distinct(...cols) {
     return this.clone(this.projectionFacet.distinct(this.context, cols));
@@ -7062,6 +7383,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Adds a LIMIT clause to the query
    * @param n - Maximum number of rows to return
    * @returns New query builder instance with the LIMIT clause
+   * @example
+   * qb.limit(10);
+   * @example
+   * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
    */
   limit(n) {
     const nextContext = this.predicateFacet.limit(this.context, n);
@@ -7071,6 +7396,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Adds an OFFSET clause to the query
    * @param n - Number of rows to skip
    * @returns New query builder instance with the OFFSET clause
+   * @example
+   * qb.offset(10);
+   * @example
+   * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
    */
   offset(n) {
     const nextContext = this.predicateFacet.offset(this.context, n);
@@ -7080,6 +7409,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Combines this query with another using UNION
    * @param query - Query to union with
    * @returns New query builder instance with the set operation
+   * @example
+   * const activeUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, true));
+   * const inactiveUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, false));
+   * qb.union(activeUsers).union(inactiveUsers);
    */
   union(query) {
     return this.clone(this.applySetOperation("UNION", query));
@@ -7088,6 +7423,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Combines this query with another using UNION ALL
    * @param query - Query to union with
    * @returns New query builder instance with the set operation
+   * @example
+   * const q1 = new SelectQueryBuilder(userTable).where(gt(userTable.columns.score, 80));
+   * const q2 = new SelectQueryBuilder(userTable).where(lt(userTable.columns.score, 20));
+   * qb.unionAll(q1).unionAll(q2);
    */
   unionAll(query) {
     return this.clone(this.applySetOperation("UNION ALL", query));
@@ -7096,6 +7435,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Combines this query with another using INTERSECT
    * @param query - Query to intersect with
    * @returns New query builder instance with the set operation
+   * @example
+   * const activeUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, true));
+   * const premiumUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.premium, true));
+   * qb.intersect(activeUsers).intersect(premiumUsers);
    */
   intersect(query) {
     return this.clone(this.applySetOperation("INTERSECT", query));
@@ -7104,6 +7449,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Combines this query with another using EXCEPT
    * @param query - Query to subtract
    * @returns New query builder instance with the set operation
+   * @example
+   * const allUsers = new SelectQueryBuilder(userTable);
+   * const inactiveUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, false));
+   * qb.except(allUsers).except(inactiveUsers); // Only active users
    */
   except(query) {
     return this.clone(this.applySetOperation("EXCEPT", query));
@@ -7112,6 +7462,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Adds a WHERE EXISTS condition to the query
    * @param subquery - Subquery to check for existence
    * @returns New query builder instance with the WHERE EXISTS condition
+   * @example
+   * const postsQuery = new SelectQueryBuilder(postTable)
+   *   .where(eq(postTable.columns.userId, col('u.id')));
+   * qb.whereExists(postsQuery);
    */
   whereExists(subquery, correlate) {
     const subAst = resolveSelectQuery(subquery);
@@ -7122,6 +7476,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Adds a WHERE NOT EXISTS condition to the query
    * @param subquery - Subquery to check for non-existence
    * @returns New query builder instance with the WHERE NOT EXISTS condition
+   * @example
+   * const postsQuery = new SelectQueryBuilder(postTable)
+   *   .where(eq(postTable.columns.userId, col('u.id')));
+   * qb.whereNotExists(postsQuery); // Users without posts
    */
   whereNotExists(subquery, correlate) {
     const subAst = resolveSelectQuery(subquery);
@@ -7176,6 +7534,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Compiles the query to SQL for a specific dialect
    * @param dialect - Database dialect to compile for
    * @returns Compiled query with SQL and parameters
+   * @example
+   * const compiled = qb.select('id', 'name')
+   *   .where(eq(userTable.columns.active, true))
+   *   .compile('postgres');
+   * console.log(compiled.sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
   compile(dialect) {
     const resolved = resolveDialectInput(dialect);
@@ -7185,6 +7548,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Converts the query to SQL string for a specific dialect
    * @param dialect - Database dialect to generate SQL for
    * @returns SQL string representation of the query
+   * @example
+   * const sql = qb.select('id', 'name')
+   *   .where(eq(userTable.columns.active, true))
+   *   .toSql('postgres');
+   * console.log(sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
   toSql(dialect) {
     return this.compile(dialect).sql;
@@ -7192,6 +7560,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
    * Gets the hydration plan for the query
    * @returns Hydration plan or undefined if none exists
+   * @example
+   * const plan = qb.include('posts').getHydrationPlan();
+   * console.log(plan?.relations); // Information about included relations
    */
   getHydrationPlan() {
     return this.context.hydration.getPlan();
@@ -7199,6 +7570,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
    * Gets the Abstract Syntax Tree (AST) representation of the query
    * @returns Query AST with hydration applied
+   * @example
+   * const ast = qb.select('id', 'name').getAST();
+   * console.log(ast.columns); // Array of column nodes
+   * console.log(ast.from); // From clause information
    */
   getAST() {
     return this.context.hydration.applyToAst(this.context.state.ast);
@@ -7229,61 +7604,6 @@ var isTableDef = (value) => {
   return true;
 };
 
-// src/orm/entity-metadata.ts
-var metadataMap = /* @__PURE__ */ new Map();
-var ensureEntityMetadata = (target) => {
-  let meta = metadataMap.get(target);
-  if (!meta) {
-    meta = {
-      target,
-      tableName: target.name || "unknown",
-      columns: {},
-      relations: {}
-    };
-    metadataMap.set(target, meta);
-  }
-  return meta;
-};
-var getEntityMetadata = (target) => {
-  return metadataMap.get(target);
-};
-var getAllEntityMetadata = () => {
-  return Array.from(metadataMap.values());
-};
-var addColumnMetadata = (target, propertyKey, column) => {
-  const meta = ensureEntityMetadata(target);
-  meta.columns[propertyKey] = { ...column };
-};
-var addRelationMetadata = (target, propertyKey, relation) => {
-  const meta = ensureEntityMetadata(target);
-  meta.relations[propertyKey] = relation;
-};
-var setEntityTableName = (target, tableName, hooks) => {
-  const meta = ensureEntityMetadata(target);
-  if (tableName && tableName.length > 0) {
-    meta.tableName = tableName;
-  }
-  if (hooks) {
-    meta.hooks = hooks;
-  }
-};
-var buildTableDef = (meta) => {
-  if (meta.table) {
-    return meta.table;
-  }
-  const columns = {};
-  for (const [key, def] of Object.entries(meta.columns)) {
-    columns[key] = {
-      ...def,
-      name: key,
-      table: meta.tableName
-    };
-  }
-  const table = defineTable(meta.tableName, columns, {}, meta.hooks);
-  meta.table = table;
-  return table;
-};
-
 // src/decorators/bootstrap.ts
 var unwrapTarget = (target) => {
   if (typeof target === "function" && target.prototype === void 0) {
@@ -7403,7 +7723,15 @@ var selectFromEntity = (ctor) => {
   if (!table) {
     throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
   }
-  return new SelectQueryBuilder(table);
+  return new SelectQueryBuilder(
+    table,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    ctor
+  );
 };
 var entityRef = (ctor) => {
   const table = getTableDefFromEntity(ctor);
@@ -8085,6 +8413,39 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
 };
 var isTableSourceNode2 = (source) => typeof source.type === "string";
 
+// src/query/target.ts
+var resolveEntityTarget = (ctor) => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators`);
+  }
+  return table;
+};
+var resolveTable = (target) => {
+  if (isTableDef(target)) {
+    return target;
+  }
+  return resolveEntityTarget(target);
+};
+
+// src/query/index.ts
+var selectFrom = (target) => {
+  const table = resolveTable(target);
+  return new SelectQueryBuilder(table);
+};
+var insertInto = (target) => {
+  const table = resolveTable(target);
+  return new InsertQueryBuilder(table);
+};
+var update = (target) => {
+  const table = resolveTable(target);
+  return new UpdateQueryBuilder(table);
+};
+var deleteFrom = (target) => {
+  const table = resolveTable(target);
+  return new DeleteQueryBuilder(table);
+};
+
 // src/core/ddl/sql-writing.ts
 var resolvePrimaryKey = (table) => {
   if (Array.isArray(table.primaryKey) && table.primaryKey.length > 0) {
@@ -12616,7 +12977,9 @@ function createPooledExecutorFactory(opts) {
   BelongsTo,
   BelongsToMany,
   Column,
+  ConstructorMaterializationStrategy,
   DefaultBelongsToReference,
+  DefaultEntityMaterializer,
   DefaultHasManyCollection,
   DefaultManyToManyCollection,
   DeleteQueryBuilder,
@@ -12632,6 +12995,7 @@ function createPooledExecutorFactory(opts) {
   Pool,
   PostgresDialect,
   PrimaryKey,
+  PrototypeMaterializationStrategy,
   RelationKinds,
   STANDARD_COLUMN_TYPES,
   SelectQueryBuilder,
@@ -12703,6 +13067,7 @@ function createPooledExecutorFactory(opts) {
   dayOfWeek,
   defineTable,
   degrees,
+  deleteFrom,
   denseRank,
   diffSchema,
   div,
@@ -12739,6 +13104,7 @@ function createPooledExecutorFactory(opts) {
   inList,
   inSubquery,
   initcap,
+  insertInto,
   instr,
   introspectSchema,
   isCaseExpressionNode,
@@ -12781,6 +13147,7 @@ function createPooledExecutorFactory(opts) {
   lt,
   lte,
   ltrim,
+  materializeAs,
   max,
   md5,
   min,
@@ -12827,6 +13194,7 @@ function createPooledExecutorFactory(opts) {
   rtrim,
   second,
   sel,
+  selectFrom,
   selectFromEntity,
   setRelations,
   sha1,
@@ -12850,6 +13218,7 @@ function createPooledExecutorFactory(opts) {
   trunc,
   truncate,
   unixTimestamp,
+  update,
   upper,
   utcNow,
   valueToOperand,