metal-orm 1.0.59 → 1.0.60

package/dist/index.js

@@ -6428,6 +6428,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
    * 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);
@@ -6485,6 +6487,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));
@@ -6495,6 +6499,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);
@@ -6507,6 +6517,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);
@@ -6519,6 +6542,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);
@@ -6531,6 +6559,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);
@@ -6541,6 +6576,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);
@@ -6554,6 +6595,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);
@@ -6568,6 +6618,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);
@@ -6578,6 +6637,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);
@@ -6588,6 +6652,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);
@@ -6598,6 +6667,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);
@@ -6608,6 +6682,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);
@@ -6619,6 +6695,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);
@@ -6629,6 +6709,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);
@@ -6639,6 +6728,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;
@@ -6668,6 +6762,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 };
@@ -6677,6 +6773,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;
@@ -6715,6 +6816,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Executes the query and returns hydrated results
    * @param ctx - ORM session context
    * @returns Promise of entity instances
+   * @example
+   * const users = await qb.select('id', 'name')
+   *   .where(eq(userTable.columns.active, true))
+   *   .execute(session);
    */
   async execute(ctx) {
     return executeHydrated(ctx, this);
@@ -6742,6 +6847,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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);
@@ -6750,6 +6859,13 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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);
@@ -6759,6 +6875,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);
@@ -6768,6 +6887,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);
@@ -6790,6 +6913,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));
@@ -6798,6 +6925,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);
@@ -6807,6 +6938,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);
@@ -6816,6 +6951,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));
@@ -6824,6 +6965,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));
@@ -6832,6 +6977,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));
@@ -6840,6 +6991,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));
@@ -6848,6 +7004,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);
@@ -6858,6 +7018,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);
@@ -6912,6 +7076,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);
@@ -6921,6 +7090,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;
@@ -6928,6 +7102,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();
@@ -6935,6 +7112,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);
@@ -7821,6 +8002,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) {
@@ -12438,6 +12652,7 @@ export {
   dayOfWeek,
   defineTable,
   degrees,
+  deleteFrom,
   denseRank,
   diffSchema,
   div,
@@ -12474,6 +12689,7 @@ export {
   inList,
   inSubquery,
   initcap,
+  insertInto,
   instr,
   introspectSchema,
   isCaseExpressionNode,
@@ -12562,6 +12778,7 @@ export {
   rtrim,
   second,
   sel,
+  selectFrom,
   selectFromEntity,
   setRelations,
   sha1,
@@ -12585,6 +12802,7 @@ export {
   trunc,
   truncate,
   unixTimestamp,
+  update,
   upper,
   utcNow,
   valueToOperand,