add TOP clause support.

src/index.ts

@@ -201,6 +201,7 @@ export * from './operation-node/json-operator-chain-node.js'
 export * from './operation-node/tuple-node.js'
 export * from './operation-node/merge-query-node.js'
 export * from './operation-node/matched-node.js'
+export * from './operation-node/top-node.js'
 
 export * from './util/column-type.js'
 export * from './util/compilable.js'

src/operation-node/delete-query-node.ts

@@ -10,6 +10,7 @@ import { OrderByNode } from './order-by-node.js'
 import { OrderByItemNode } from './order-by-item-node.js'
 import { ExplainNode } from './explain-node.js'
 import { UsingNode } from './using-node.js'
+import { TopNode } from './top-node.js'
 
 export interface DeleteQueryNode extends OperationNode {
   readonly kind: 'DeleteQueryNode'
@@ -22,6 +23,7 @@ export interface DeleteQueryNode extends OperationNode {
   readonly orderBy?: OrderByNode
   readonly limit?: LimitNode
   readonly explain?: ExplainNode
+  readonly top?: TopNode
 }
 
 /**

src/operation-node/insert-query-node.ts

@@ -6,6 +6,7 @@ import { OnDuplicateKeyNode } from './on-duplicate-key-node.js'
 import { OperationNode } from './operation-node.js'
 import { ReturningNode } from './returning-node.js'
 import { TableNode } from './table-node.js'
+import { TopNode } from './top-node.js'
 import { WithNode } from './with-node.js'
 
 export type InsertQueryNodeProps = Omit<InsertQueryNode, 'kind' | 'into'>
@@ -23,6 +24,7 @@ export interface InsertQueryNode extends OperationNode {
   readonly replace?: boolean
   readonly explain?: ExplainNode
   readonly defaultValues?: boolean
+  readonly top?: TopNode
 }
 
 /**

src/operation-node/operation-node-transformer.ts

@@ -90,6 +90,7 @@ import { TupleNode } from './tuple-node.js'
 import { MergeQueryNode } from './merge-query-node.js'
 import { MatchedNode } from './matched-node.js'
 import { AddIndexNode } from './add-index-node.js'
+import { TopNode } from './top-node.js'
 
 /**
  * Transforms an operation node tree into another one.
@@ -214,6 +215,7 @@ export class OperationNodeTransformer {
     MergeQueryNode: this.transformMergeQuery.bind(this),
     MatchedNode: this.transformMatched.bind(this),
     AddIndexNode: this.transformAddIndex.bind(this),
+    TopNode: this.transformTop.bind(this),
   })
 
   transformNode<T extends OperationNode | undefined>(node: T): T {
@@ -260,6 +262,7 @@ export class OperationNodeTransformer {
       having: this.transformNode(node.having),
       explain: this.transformNode(node.explain),
       setOperations: this.transformNodeList(node.setOperations),
+      top: this.transformNode(node.top),
     })
   }
 
@@ -375,6 +378,7 @@ export class OperationNodeTransformer {
       replace: node.replace,
       explain: this.transformNode(node.explain),
       defaultValues: node.defaultValues,
+      top: this.transformNode(node.top),
     })
   }
 
@@ -397,6 +401,7 @@ export class OperationNodeTransformer {
       orderBy: this.transformNode(node.orderBy),
       limit: this.transformNode(node.limit),
       explain: this.transformNode(node.explain),
+      top: this.transformNode(node.top),
     })
   }
 
@@ -500,6 +505,7 @@ export class OperationNodeTransformer {
       returning: this.transformNode(node.returning),
       with: this.transformNode(node.with),
       explain: this.transformNode(node.explain),
+      top: this.transformNode(node.top),
     })
   }
 
@@ -1015,6 +1021,14 @@ export class OperationNodeTransformer {
     })
   }
 
+  protected transformTop(node: TopNode): TopNode {
+    return requireAllProps<TopNode>({
+      kind: 'TopNode',
+      expression: node.expression,
+      modifiers: node.modifiers,
+    })
+  }
+
   protected transformDataType(node: DataTypeNode): DataTypeNode {
     // An Object.freezed leaf node. No need to clone.
     return node

src/operation-node/operation-node-visitor.ts

@@ -92,6 +92,7 @@ import { TupleNode } from './tuple-node.js'
 import { MergeQueryNode } from './merge-query-node.js'
 import { MatchedNode } from './matched-node.js'
 import { AddIndexNode } from './add-index-node.js'
+import { TopNode } from './top-node.js'
 
 export abstract class OperationNodeVisitor {
   protected readonly nodeStack: OperationNode[] = []
@@ -191,6 +192,7 @@ export abstract class OperationNodeVisitor {
     MergeQueryNode: this.visitMergeQuery.bind(this),
     MatchedNode: this.visitMatched.bind(this),
     AddIndexNode: this.visitAddIndex.bind(this),
+    TopNode: this.visitTop.bind(this),
   })
 
   protected readonly visitNode = (node: OperationNode): void => {
@@ -234,17 +236,17 @@ export abstract class OperationNodeVisitor {
   protected abstract visitDropIndex(node: DropIndexNode): void
   protected abstract visitList(node: ListNode): void
   protected abstract visitPrimaryKeyConstraint(
-    node: PrimaryKeyConstraintNode
+    node: PrimaryKeyConstraintNode,
   ): void
   protected abstract visitUniqueConstraint(node: UniqueConstraintNode): void
   protected abstract visitReferences(node: ReferencesNode): void
   protected abstract visitCheckConstraint(node: CheckConstraintNode): void
   protected abstract visitWith(node: WithNode): void
   protected abstract visitCommonTableExpression(
-    node: CommonTableExpressionNode
+    node: CommonTableExpressionNode,
   ): void
   protected abstract visitCommonTableExpressionName(
-    node: CommonTableExpressionNameNode
+    node: CommonTableExpressionNameNode,
   ): void
   protected abstract visitHaving(node: HavingNode): void
   protected abstract visitCreateSchema(node: CreateSchemaNode): void
@@ -257,13 +259,13 @@ export abstract class OperationNodeVisitor {
   protected abstract visitAddConstraint(node: AddConstraintNode): void
   protected abstract visitDropConstraint(node: DropConstraintNode): void
   protected abstract visitForeignKeyConstraint(
-    node: ForeignKeyConstraintNode
+    node: ForeignKeyConstraintNode,
   ): void
   protected abstract visitDataType(node: DataTypeNode): void
   protected abstract visitSelectAll(node: SelectAllNode): void
   protected abstract visitIdentifier(node: IdentifierNode): void
   protected abstract visitSchemableIdentifier(
-    node: SchemableIdentifierNode
+    node: SchemableIdentifierNode,
   ): void
   protected abstract visitValue(node: ValueNode): void
   protected abstract visitPrimitiveValueList(node: PrimitiveValueListNode): void
@@ -298,4 +300,5 @@ export abstract class OperationNodeVisitor {
   protected abstract visitMergeQuery(node: MergeQueryNode): void
   protected abstract visitMatched(node: MatchedNode): void
   protected abstract visitAddIndex(node: AddIndexNode): void
+  protected abstract visitTop(node: TopNode): void
 }

src/operation-node/operation-node.ts

@@ -88,6 +88,7 @@ export type OperationNodeKind =
   | 'MergeQueryNode'
   | 'MatchedNode'
   | 'AddIndexNode'
+  | 'TopNode'
 
 export interface OperationNode {
   readonly kind: OperationNodeKind

src/operation-node/query-node.ts

@@ -12,6 +12,7 @@ import { ExplainNode } from './explain-node.js'
 import { ExplainFormat } from '../util/explainable.js'
 import { Expression } from '../expression/expression.js'
 import { MergeQueryNode } from './merge-query-node.js'
+import { TopModifier, TopNode } from './top-node.js'
 
 export type QueryNode =
   | SelectQueryNode
@@ -24,6 +25,7 @@ type HasJoins = { joins?: ReadonlyArray<JoinNode> }
 type HasWhere = { where?: WhereNode }
 type HasReturning = { returning?: ReturningNode }
 type HasExplain = { explain?: ExplainNode }
+type HasTop = { top?: TopNode }
 
 /**
  * @internal
@@ -84,4 +86,15 @@ export const QueryNode = freeze({
       explain: ExplainNode.create(format, options?.toOperationNode()),
     })
   },
+
+  cloneWithTop<T extends HasTop>(
+    node: T,
+    expression: number | bigint,
+    modifiers?: TopModifier
+  ): T {
+    return freeze({
+      ...node,
+      top: TopNode.create(expression, modifiers),
+    })
+  },
 })

src/operation-node/select-query-node.ts

@@ -15,6 +15,7 @@ import { WithNode } from './with-node.js'
 import { SelectModifierNode } from './select-modifier-node.js'
 import { ExplainNode } from './explain-node.js'
 import { SetOperationNode } from './set-operation-node.js'
+import { TopNode } from './top-node.js'
 
 export interface SelectQueryNode extends OperationNode {
   readonly kind: 'SelectQueryNode'
@@ -33,6 +34,7 @@ export interface SelectQueryNode extends OperationNode {
   readonly having?: HavingNode
   readonly explain?: ExplainNode
   readonly setOperations?: ReadonlyArray<SetOperationNode>
+  readonly top?: TopNode
 }
 
 /**

src/operation-node/top-node.ts

@@ -0,0 +1,27 @@
+import { freeze } from '../util/object-utils.js'
+import { OperationNode } from './operation-node.js'
+
+export type TopModifier = 'percent' | 'with ties' | 'percent with ties'
+
+export interface TopNode extends OperationNode {
+  readonly kind: 'TopNode'
+  readonly expression: number | bigint
+  readonly modifiers?: TopModifier
+}
+
+/**
+ * @internal
+ */
+export const TopNode = freeze({
+  is(node: OperationNode): node is TopNode {
+    return node.kind === 'TopNode'
+  },
+
+  create(expression: number | bigint, modifiers?: TopModifier): TopNode {
+    return freeze({
+      kind: 'TopNode',
+      expression,
+      modifiers,
+    })
+  },
+})

src/operation-node/update-query-node.ts

@@ -9,6 +9,7 @@ import { WhereNode } from './where-node.js'
 import { WithNode } from './with-node.js'
 import { FromNode } from './from-node.js'
 import { ExplainNode } from './explain-node.js'
+import { TopNode } from './top-node.js'
 
 export type UpdateValuesNode = ValueListNode | PrimitiveValueListNode
 
@@ -22,6 +23,7 @@ export interface UpdateQueryNode extends OperationNode {
   readonly returning?: ReturningNode
   readonly with?: WithNode
   readonly explain?: ExplainNode
+  readonly top?: TopNode
 }
 
 /**

src/query-builder/delete-query-builder.ts

@@ -71,6 +71,7 @@ import {
   ValueExpression,
   parseValueExpression,
 } from '../parser/value-parser.js'
+import { TopNode } from '../operation-node/top-node.js'
 
 export class DeleteQueryBuilder<DB, TB extends keyof DB, O>
   implements
@@ -134,6 +135,55 @@ export class DeleteQueryBuilder<DB, TB extends keyof DB, O>
     })
   }
 
+  /**
+   * Changes a `delete from` query into a `delete top from` query.
+   *
+   * `top` clause is only supported by some dialects like MS SQL Server.
+   *
+   * ### Examples
+   *
+   * Delete the first 5 rows:
+   *
+   * ```ts
+   * await db
+   *   .deleteFrom('person')
+   *   .top(5)
+   *   .where('age', '>', 18)
+   *   .executeTakeFirstOrThrow()
+   * ```
+   *
+   * The generated SQL (MS SQL Server):
+   *
+   * ```sql
+   * delete top(5) from "person" where "age" > @1
+   * ```
+   *
+   * Delete the first 50% of rows:
+   *
+   * ```ts
+   * await db
+   *   .deleteFrom('person')
+   *   .top(50, 'percent')
+   *   .where('age', '>', 18)
+   *   .executeTakeFirstOrThrow()
+   * ```
+   *
+   * The generated SQL (MS SQL Server):
+   *
+   * ```sql
+   * delete top(50) percent from "person" where "age" > @1
+   * ```
+   */
+  top(
+    top: number | bigint,
+    modifiers?: 'percent'
+  ): DeleteQueryBuilder<DB, TB, O> {
+    return new DeleteQueryBuilder({
+      ...this.#props,
+      queryNode: QueryNode.cloneWithTop(this.#props.queryNode, top, modifiers),
+    })
+  }
+
   /**
    * Adds a `using` clause to the query.
    *

src/query-builder/insert-query-builder.ts

@@ -361,6 +361,63 @@ export class InsertQueryBuilder<DB, TB extends keyof DB, O>
     })
   }
 
+  /**
+   * Changes an `insert into` query to an `insert top into` query.
+   *
+   * `top` clause is only supported by some dialects like MS SQL Server.
+   *
+   * ### Examples
+   *
+   * Insert the first 5 rows:
+   *
+   * ```ts
+   * await db.insertInto('person')
+   *   .top(5)
+   *   .columns(['first_name', 'gender'])
+   *   .expression(
+   *     (eb) => eb.selectFrom('pet').select(['name', sql.lit('other').as('gender')])
+   *   )
+   *   .execute()
+   * ```
+   *
+   * The generated SQL (MS SQL Server):
+   *
+   * ```sql
+   * insert top(5) into "person" ("first_name", "gender") select "name", 'other' as "gender" from "pet"
+   * ```
+   *
+   * Insert the first 50 percent of rows:
+   *
+   * ```ts
+   * await db.insertInto('person')
+   *   .top(50, 'percent')
+   *   .columns(['first_name', 'gender'])
+   *   .expression(
+   *     (eb) => eb.selectFrom('pet').select(['name', sql.lit('other').as('gender')])
+   *   )
+   *   .execute()
+   * ```
+   *
+   * The generated SQL (MS SQL Server):
+   *
+   * ```sql
+   * insert top(50) percent into "person" ("first_name", "gender") select "name", 'other' as "gender" from "pet"
+   * ```
+   */
+  top(
+    expression: number | bigint,
+    modifiers?: 'percent'
+  ): InsertQueryBuilder<DB, TB, O> {
+    return new InsertQueryBuilder({
+      ...this.#props,
+      queryNode: QueryNode.cloneWithTop(
+        this.#props.queryNode,
+        expression,
+        modifiers
+      ),
+    })
+  }
+
   /**
    * Adds an `on conflict` clause to the query.
    *