metal-orm 1.0.0

package/src/dialect/abstract.ts

@@ -0,0 +1,221 @@
+import { SelectQueryNode } from '../ast/query';
+import {
+  ExpressionNode,
+  BinaryExpressionNode,
+  LogicalExpressionNode,
+  NullExpressionNode,
+  InExpressionNode,
+  ExistsExpressionNode,
+  LiteralNode,
+  ColumnNode,
+  OperandNode,
+  FunctionNode,
+  JsonPathNode,
+  ScalarSubqueryNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  BetweenExpressionNode
+} from '../ast/expression';
+
+export interface CompilerContext {
+  params: unknown[];
+  addParameter(value: unknown): string;
+}
+
+export interface CompiledQuery {
+  sql: string;
+  params: unknown[];
+}
+
+export abstract class Dialect {
+  compileSelect(ast: SelectQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileSelectAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+
+  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
+
+  abstract quoteIdentifier(id: string): string;
+
+  protected compileWhere(where: ExpressionNode | undefined, ctx: CompilerContext): string {
+    if (!where) return '';
+    return ` WHERE ${this.compileExpression(where, ctx)}`;
+  }
+
+  /**
+   * Gera a subquery para EXISTS.
+   * Regra: sempre força SELECT 1, ignorando a lista de colunas.
+   * Mantém FROM, JOINs, WHERE, GROUP BY, ORDER BY, LIMIT/OFFSET.
+   * Não adiciona ';' no final.
+   */
+  protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const full = this.compileSelectAst(ast, ctx).trim().replace(/;$/, '');
+    const upper = full.toUpperCase();
+    const fromIndex = upper.indexOf(' FROM ');
+    if (fromIndex === -1) {
+      return full;
+    }
+
+    const tail = full.slice(fromIndex);
+    return `SELECT 1${tail}`;
+  }
+
+  protected createCompilerContext(): CompilerContext {
+    const params: unknown[] = [];
+    let counter = 0;
+    return {
+      params,
+      addParameter: (value: unknown) => {
+        counter += 1;
+        params.push(value);
+        return this.formatPlaceholder(counter);
+      }
+    };
+  }
+
+  protected formatPlaceholder(index: number): string {
+    return '?';
+  }
+
+  private readonly expressionCompilers: Map<string, (node: ExpressionNode, ctx: CompilerContext) => string>;
+  private readonly operandCompilers: Map<string, (node: OperandNode, ctx: CompilerContext) => string>;
+
+  protected constructor() {
+    this.expressionCompilers = new Map();
+    this.operandCompilers = new Map();
+    this.registerDefaultOperandCompilers();
+    this.registerDefaultExpressionCompilers();
+  }
+
+  protected registerExpressionCompiler<T extends ExpressionNode>(type: T['type'], compiler: (node: T, ctx: CompilerContext) => string): void {
+    this.expressionCompilers.set(type, compiler as (node: ExpressionNode, ctx: CompilerContext) => string);
+  }
+
+  protected registerOperandCompiler<T extends OperandNode>(type: T['type'], compiler: (node: T, ctx: CompilerContext) => string): void {
+    this.operandCompilers.set(type, compiler as (node: OperandNode, ctx: CompilerContext) => string);
+  }
+
+  protected compileExpression(node: ExpressionNode, ctx: CompilerContext): string {
+    const compiler = this.expressionCompilers.get(node.type);
+    return compiler ? compiler(node, ctx) : '';
+  }
+
+  protected compileOperand(node: OperandNode, ctx: CompilerContext): string {
+    const compiler = this.operandCompilers.get(node.type);
+    return compiler ? compiler(node, ctx) : '';
+  }
+
+  private registerDefaultExpressionCompilers(): void {
+    this.registerExpressionCompiler('BinaryExpression', (binary: BinaryExpressionNode, ctx) => {
+      const left = this.compileOperand(binary.left, ctx);
+      const right = this.compileOperand(binary.right, ctx);
+      const base = `${left} ${binary.operator} ${right}`;
+      if (binary.escape) {
+        const escapeOperand = this.compileOperand(binary.escape, ctx);
+        return `${base} ESCAPE ${escapeOperand}`;
+      }
+      return base;
+    });
+
+    this.registerExpressionCompiler('LogicalExpression', (logical: LogicalExpressionNode, ctx) => {
+      if (logical.operands.length === 0) return '';
+      const parts = logical.operands.map(op => {
+        const compiled = this.compileExpression(op, ctx);
+        return op.type === 'LogicalExpression' ? `(${compiled})` : compiled;
+      });
+      return parts.join(` ${logical.operator} `);
+    });
+
+    this.registerExpressionCompiler('NullExpression', (nullExpr: NullExpressionNode, ctx) => {
+      const left = this.compileOperand(nullExpr.left, ctx);
+      return `${left} ${nullExpr.operator}`;
+    });
+
+    this.registerExpressionCompiler('InExpression', (inExpr: InExpressionNode, ctx) => {
+      const left = this.compileOperand(inExpr.left, ctx);
+      const values = inExpr.right.map(v => this.compileOperand(v, ctx)).join(', ');
+      return `${left} ${inExpr.operator} (${values})`;
+    });
+
+    this.registerExpressionCompiler('ExistsExpression', (existsExpr: ExistsExpressionNode, ctx) => {
+      const subquerySql = this.compileSelectForExists(existsExpr.subquery, ctx);
+      return `${existsExpr.operator} (${subquerySql})`;
+    });
+
+    this.registerExpressionCompiler('BetweenExpression', (betweenExpr: BetweenExpressionNode, ctx) => {
+      const left = this.compileOperand(betweenExpr.left, ctx);
+      const lower = this.compileOperand(betweenExpr.lower, ctx);
+      const upper = this.compileOperand(betweenExpr.upper, ctx);
+      return `${left} ${betweenExpr.operator} ${lower} AND ${upper}`;
+    });
+  }
+
+  private registerDefaultOperandCompilers(): void {
+    this.registerOperandCompiler('Literal', (literal: LiteralNode, ctx) => ctx.addParameter(literal.value));
+
+    this.registerOperandCompiler('Column', (column: ColumnNode, _ctx) => {
+      return `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`;
+    });
+    this.registerOperandCompiler('Function', (fnNode: FunctionNode, ctx) => {
+      const args = fnNode.args.map(arg => this.compileOperand(arg, ctx)).join(', ');
+      return `${fnNode.name}(${args})`;
+    });
+    this.registerOperandCompiler('JsonPath', (path: JsonPathNode, _ctx) => this.compileJsonPath(path));
+
+    this.registerOperandCompiler('ScalarSubquery', (node: ScalarSubqueryNode, ctx) => {
+      const sql = this.compileSelectAst(node.query, ctx).trim().replace(/;$/, '');
+      return `(${sql})`;
+    });
+
+    this.registerOperandCompiler('CaseExpression', (node: CaseExpressionNode, ctx) => {
+      const parts = ['CASE'];
+      for (const { when, then } of node.conditions) {
+        parts.push(`WHEN ${this.compileExpression(when, ctx)} THEN ${this.compileOperand(then, ctx)}`);
+      }
+      if (node.else) {
+        parts.push(`ELSE ${this.compileOperand(node.else, ctx)}`);
+      }
+      parts.push('END');
+      return parts.join(' ');
+    });
+
+    this.registerOperandCompiler('WindowFunction', (node: WindowFunctionNode, ctx) => {
+      let result = `${node.name}(`;
+      if (node.args.length > 0) {
+        result += node.args.map(arg => this.compileOperand(arg, ctx)).join(', ');
+      }
+      result += ') OVER (';
+
+      const parts: string[] = [];
+
+      if (node.partitionBy && node.partitionBy.length > 0) {
+        const partitionClause = 'PARTITION BY ' + node.partitionBy.map(col =>
+          `${this.quoteIdentifier(col.table)}.${this.quoteIdentifier(col.name)}`
+        ).join(', ');
+        parts.push(partitionClause);
+      }
+
+      if (node.orderBy && node.orderBy.length > 0) {
+        const orderClause = 'ORDER BY ' + node.orderBy.map(o =>
+          `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`
+        ).join(', ');
+        parts.push(orderClause);
+      }
+
+      result += parts.join(' ');
+      result += ')';
+
+      return result;
+    });
+  }
+
+  // Default fallback, should be overridden by dialects if supported
+  protected compileJsonPath(node: JsonPathNode): string {
+    throw new Error("JSON Path not supported by this dialect");
+  }
+}

package/src/dialect/mssql/index.ts

@@ -0,0 +1,89 @@
+import { CompilerContext, Dialect } from '../abstract';
+import { SelectQueryNode } from '../../ast/query';
+import { JsonPathNode } from '../../ast/expression';
+
+export class SqlServerDialect extends Dialect {
+  public constructor() {
+    super();
+  }
+
+  quoteIdentifier(id: string): string {
+    return `[${id}]`;
+  }
+
+  protected compileJsonPath(node: JsonPathNode): string {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    // SQL Server uses JSON_VALUE(col, '$.path')
+    return `JSON_VALUE(${col}, '${node.path}')`;
+  }
+
+  protected formatPlaceholder(index: number): string {
+    return `@p${index}`;
+  }
+
+  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const columns = ast.columns.map(c => {
+      let expr = '';
+      if (c.type === 'Function') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'Column') {
+        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
+      } else if (c.type === 'ScalarSubquery') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'WindowFunction') {
+        expr = this.compileOperand(c, ctx);
+      }
+
+      if (c.alias) {
+        if (c.alias.includes('(')) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(', ');
+
+    const distinct = ast.distinct ? 'DISTINCT ' : '';
+    const from = `${this.quoteIdentifier(ast.from.name)}`;
+
+    const joins = ast.joins.map(j => {
+      const table = this.quoteIdentifier(j.table.name);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(' ');
+    const whereClause = this.compileWhere(ast.where, ctx);
+
+    const groupBy = ast.groupBy && ast.groupBy.length > 0
+      ? ' GROUP BY ' + ast.groupBy.map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(', ')
+      : '';
+
+    const having = ast.having
+      ? ` HAVING ${this.compileExpression(ast.having, ctx)}`
+      : '';
+
+    const orderBy = ast.orderBy && ast.orderBy.length > 0
+      ? ' ORDER BY ' + ast.orderBy.map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(', ')
+      : '';
+
+    let pagination = '';
+    if (ast.limit || ast.offset) {
+      const off = ast.offset || 0;
+      const orderClause = orderBy || ' ORDER BY (SELECT NULL)';
+      pagination = `${orderClause} OFFSET ${off} ROWS`;
+      if (ast.limit) {
+        pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
+      }
+      return `SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${pagination};`;
+    }
+
+    const ctes = ast.ctes && ast.ctes.length > 0
+      ? 'WITH ' + ast.ctes.map(cte => {
+        // MSSQL does not use RECURSIVE keyword
+        const name = this.quoteIdentifier(cte.name);
+        const cols = cte.columns ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})` : '';
+        const query = this.compileSelectAst(cte.query, ctx).trim().replace(/;$/, '');
+        return `${name}${cols} AS (${query})`;
+      }).join(', ') + ' '
+      : '';
+
+    return `${ctes}SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${orderBy};`;
+  }
+}

package/src/dialect/mysql/index.ts

@@ -0,0 +1,81 @@
+import { CompilerContext, Dialect } from '../abstract';
+import { SelectQueryNode } from '../../ast/query';
+import { JsonPathNode } from '../../ast/expression';
+
+export class MySqlDialect extends Dialect {
+  public constructor() {
+    super();
+  }
+
+  quoteIdentifier(id: string): string {
+    return `\`${id}\``;
+  }
+
+  protected compileJsonPath(node: JsonPathNode): string {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    // MySQL 5.7+ uses col->'$.path'
+    return `${col}->'${node.path}'`;
+  }
+
+  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const columns = ast.columns.map(c => {
+      let expr = '';
+      if (c.type === 'Function') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'Column') {
+        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
+      } else if (c.type === 'ScalarSubquery') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'WindowFunction') {
+        expr = this.compileOperand(c, ctx);
+      }
+
+      if (c.alias) {
+        if (c.alias.includes('(')) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(', ');
+
+    const distinct = ast.distinct ? 'DISTINCT ' : '';
+    const from = `${this.quoteIdentifier(ast.from.name)}`;
+
+    const joins = ast.joins.map(j => {
+      const table = this.quoteIdentifier(j.table.name);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(' ');
+    const whereClause = this.compileWhere(ast.where, ctx);
+
+    const groupBy = ast.groupBy && ast.groupBy.length > 0
+      ? ' GROUP BY ' + ast.groupBy.map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(', ')
+      : '';
+
+    const having = ast.having
+      ? ` HAVING ${this.compileExpression(ast.having, ctx)}`
+      : '';
+
+    const orderBy = ast.orderBy && ast.orderBy.length > 0
+      ? ' ORDER BY ' + ast.orderBy.map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(', ')
+      : '';
+
+    const limit = ast.limit ? ` LIMIT ${ast.limit}` : '';
+    const offset = ast.offset ? ` OFFSET ${ast.offset}` : '';
+
+    const ctes = ast.ctes && ast.ctes.length > 0
+      ? (() => {
+        const hasRecursive = ast.ctes.some(cte => cte.recursive);
+        const prefix = hasRecursive ? 'WITH RECURSIVE ' : 'WITH ';
+        const cteDefs = ast.ctes.map(cte => {
+          const name = this.quoteIdentifier(cte.name);
+          const cols = cte.columns ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})` : '';
+          const query = this.compileSelectAst(cte.query, ctx).trim().replace(/;$/, '');
+          return `${name}${cols} AS (${query})`;
+        }).join(', ');
+        return prefix + cteDefs + ' ';
+      })()
+      : '';
+
+    return `${ctes}SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${orderBy}${limit}${offset};`;
+  }
+}

package/src/dialect/sqlite/index.ts

@@ -0,0 +1,85 @@
+import { CompilerContext, Dialect } from '../abstract';
+import { SelectQueryNode } from '../../ast/query';
+import { JsonPathNode } from '../../ast/expression';
+
+export class SqliteDialect extends Dialect {
+  public constructor() {
+    super();
+  }
+
+  quoteIdentifier(id: string): string {
+    return `"${id}"`;
+  }
+
+  protected compileJsonPath(node: JsonPathNode): string {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    // SQLite uses json_extract(col, '$.path')
+    return `json_extract(${col}, '${node.path}')`;
+  }
+
+  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const columns = ast.columns.map(c => {
+      let expr = '';
+      if (c.type === 'Function') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'Column') {
+        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
+      } else if (c.type === 'ScalarSubquery') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'CaseExpression') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'WindowFunction') {
+        expr = this.compileOperand(c, ctx);
+      }
+
+      // Handle alias
+      if (c.alias) {
+        // Backward compat for the raw string parsing alias hack in playground
+        if (c.alias.includes('(')) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(', ');
+
+    const distinct = ast.distinct ? 'DISTINCT ' : '';
+    const from = `${this.quoteIdentifier(ast.from.name)}`;
+
+    const joins = ast.joins.map(j => {
+      const table = this.quoteIdentifier(j.table.name);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(' ');
+    const whereClause = this.compileWhere(ast.where, ctx);
+
+    const groupBy = ast.groupBy && ast.groupBy.length > 0
+      ? ' GROUP BY ' + ast.groupBy.map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(', ')
+      : '';
+
+    const having = ast.having
+      ? ` HAVING ${this.compileExpression(ast.having, ctx)}`
+      : '';
+
+    const orderBy = ast.orderBy && ast.orderBy.length > 0
+      ? ' ORDER BY ' + ast.orderBy.map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(', ')
+      : '';
+
+    const limit = ast.limit ? ` LIMIT ${ast.limit}` : '';
+    const offset = ast.offset ? ` OFFSET ${ast.offset}` : '';
+
+    const ctes = ast.ctes && ast.ctes.length > 0
+      ? (() => {
+        const hasRecursive = ast.ctes.some(cte => cte.recursive);
+        const prefix = hasRecursive ? 'WITH RECURSIVE ' : 'WITH ';
+        const cteDefs = ast.ctes.map(cte => {
+          const name = this.quoteIdentifier(cte.name);
+          const cols = cte.columns ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})` : '';
+          const query = this.compileSelectAst(cte.query, ctx).trim().replace(/;$/, '');
+          return `${name}${cols} AS (${query})`;
+        }).join(', ');
+        return prefix + cteDefs + ' ';
+      })()
+      : '';
+
+    return `${ctes}SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${orderBy}${limit}${offset};`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+
+export * from './schema/table';
+export * from './schema/column';
+export * from './schema/relation';
+export * from './builder/select';
+export * from './ast/expression';
+export * from './dialect/mysql';
+export * from './dialect/mssql';
+export * from './dialect/sqlite';
+export * from './runtime/als';
+export * from './runtime/hydration';
+export * from './codegen/typescript';

package/src/playground/features/playground/api/types.ts

@@ -0,0 +1,16 @@
+import type { QueryResult } from '../common/IDatabaseClient';
+
+export interface QueryExecutionResult {
+  sql: string;
+  params: unknown[];
+  typescriptCode: string;
+  results: QueryResult[];
+  hydratedResults?: Record<string, any>[];
+  error: string | null;
+  executionTime: number;
+}
+
+export interface ApiStatusResponse {
+  ready: boolean;
+  error: string | null;
+}

package/src/playground/features/playground/clients/MockClient.ts

@@ -0,0 +1,17 @@
+import { IDatabaseClient, QueryResult } from "../common/IDatabaseClient";
+import { DialectName } from "../../../../constants/sql";
+
+export type SupportedDialect = DialectName;
+
+export class MockClient implements IDatabaseClient {
+    isReady: boolean = true;
+    error: string | null = null;
+
+    constructor(dialect: SupportedDialect) {
+        this.error = `${dialect} is not supported yet.`;
+    }
+
+    public async executeSql(sql: string, _params: unknown[] = []): Promise<QueryResult[]> {
+        return [];
+    }
+}

package/src/playground/features/playground/clients/SqliteClient.ts

@@ -0,0 +1,57 @@
+import { IDatabaseClient, QueryResult } from "../common/IDatabaseClient";
+import { SEED_SQL } from "../data/seed";
+import sqlite3 from 'sqlite3';
+
+export class SqliteClient implements IDatabaseClient {
+    isReady: boolean = false;
+    error: string | null = null;
+    private db: sqlite3.Database | null = null;
+
+    constructor() {
+        this.initDB();
+    }
+
+    private async initDB() {
+        try {
+            this.db = new sqlite3.Database(':memory:');
+            await new Promise<void>((resolve, reject) => {
+                this.db!.exec(SEED_SQL, (err) => {
+                    if (err) reject(err);
+                    else resolve();
+                });
+            });
+            this.isReady = true;
+        } catch (e) {
+            console.error("Failed to load DB", e);
+            this.error = "Failed to initialize SQLite database.";
+        }
+    }
+
+    public async executeSql(sql: string, params: unknown[] = []): Promise<QueryResult[]> {
+        if (!this.db) {
+            this.error = "Database not ready.";
+            return [];
+        }
+
+        return new Promise((resolve, reject) => {
+            this.db!.all(sql, params, (err, rows) => {
+                if (err) {
+                    this.error = err.message;
+                    resolve([]);
+                } else {
+                    this.error = null;
+                    if (rows.length === 0) {
+                        resolve([]);
+                    } else {
+                        const columns = Object.keys(rows[0]);
+                        const values = rows.map(row => columns.map(col => row[col]));
+                        resolve([{
+                            columns,
+                            values,
+                        }]);
+                    }
+                }
+            });
+        });
+    }
+}

package/src/playground/features/playground/common/IDatabaseClient.ts

@@ -0,0 +1,10 @@
+export type QueryResult = {
+  columns: string[];
+  values: any[][];
+};
+
+export interface IDatabaseClient {
+  isReady: boolean;
+  error: string | null;
+  executeSql(sql: string, params?: unknown[]): Promise<QueryResult[]>;
+}

package/src/playground/features/playground/data/scenarios/aggregation.ts

@@ -0,0 +1,36 @@
+import { eq, count, sum } from '../../../../../ast/expression';
+import { createLiteral } from '../../../../../builder/select';
+import { Users, Orders } from '../schema';
+import { Scenario } from './types';
+
+export const AGGREGATION_SCENARIOS = [
+    {
+        id: 'analytics',
+        category: 'Aggregation',
+        title: 'Sales Analytics',
+        description: 'Aggregating sales data using GROUP BY and sorting with ORDER BY DESC.',
+        build: (qb) => qb
+            .select({
+                user: Users.columns.name,
+                orderCount: count(Orders.columns.id)
+            })
+            .joinRelation('orders')
+            .groupBy(Users.columns.name)
+            .orderBy(Users.columns.name, 'DESC')
+    },
+    {
+        id: 'revenue_by_role',
+        category: 'Aggregation',
+        title: 'Revenue by Role',
+        description: 'Summing completed order totals and grouping the result by user role.',
+        build: (qb) => qb
+            .select({
+                role: Users.columns.role,
+                revenue: sum(Orders.columns.total)
+            })
+            .joinRelation('orders')
+            .where(eq(Orders.columns.status, createLiteral('completed')))
+            .groupBy(Users.columns.role)
+            .orderBy(Users.columns.role, 'ASC')
+    }
+];

package/src/playground/features/playground/data/scenarios/basics.ts

@@ -0,0 +1,25 @@
+import { Users } from '../schema';
+import { createScenario } from './types';
+
+export const BASIC_SCENARIOS = [
+    createScenario({
+        id: 'basic',
+        category: 'Basics',
+        title: 'Hello World',
+        description: 'A basic projection query fetching specific columns from the Users table.',
+        build: (qb) => qb.select({ id: Users.columns.id, name: Users.columns.name }).limit(5)
+    }),
+    createScenario({
+        id: 'aliased_projection',
+        category: 'Basics',
+        title: 'Aliased Projection',
+        description: 'Expose friendly aliases when projecting columns for DTOs.',
+        build: (qb) => qb
+            .select({
+                userId: Users.columns.id,
+                userName: Users.columns.name,
+                userRole: Users.columns.role
+            })
+            .limit(4)
+    })
+];