metal-orm 1.0.1 → 1.0.3

package/src/schema/table.ts

@@ -1,14 +1,38 @@
 import { ColumnDef } from './column';
 import { RelationDef } from './relation';
 
+/**
+ * Definition of a database table with its columns and relationships
+ * @typeParam T - Type of the columns record
+ */
 export interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDef>> {
+  /** Name of the table */
   name: string;
+  /** Record of column definitions keyed by column name */
   columns: T;
+  /** Record of relationship definitions keyed by relation name */
   relations: Record<string, RelationDef>;
 }
 
+/**
+ * Creates a table definition with columns and relationships
+ * @typeParam T - Type of the columns record
+ * @param name - Name of the table
+ * @param columns - Record of column definitions
+ * @param relations - Record of relationship definitions (optional)
+ * @returns Complete table definition with runtime-filled column metadata
+ *
+ * @example
+ * ```typescript
+ * const usersTable = defineTable('users', {
+ *   id: col.primaryKey(col.int()),
+ *   name: col.varchar(255),
+ *   email: col.varchar(255)
+ * });
+ * ```
+ */
 export const defineTable = <T extends Record<string, ColumnDef>>(
-    name: string, 
+    name: string,
     columns: T,
     relations: Record<string, RelationDef> = {}
 ): TableDef<T> => {
@@ -17,6 +41,6 @@ export const defineTable = <T extends Record<string, ColumnDef>>(
     (acc as any)[key] = { ...def, name: key, table: name };
     return acc;
   }, {} as T);
-  
+
   return { name, columns: colsWithNames, relations };
-};
+};

package/src/utils/join-node.ts

@@ -0,0 +1,20 @@
+import { JoinNode } from '../ast/join';
+import { ExpressionNode } from '../ast/expression';
+import { JoinKind } from '../constants/sql';
+
+/**
+ * Creates a JoinNode ready for AST insertion.
+ * Centralizing this avoids copy/pasted object literals when multiple services need to synthesize joins.
+ */
+export const createJoinNode = (
+  kind: JoinKind,
+  tableName: string,
+  condition: ExpressionNode,
+  relationName?: string
+): JoinNode => ({
+  type: 'Join',
+  kind,
+  table: { type: 'Table', name: tableName },
+  condition,
+  relationName
+});

package/src/utils/raw-column-parser.ts

@@ -0,0 +1,32 @@
+import { ColumnNode } from '../ast/expression';
+import { CommonTableExpressionNode } from '../ast/query';
+
+/**
+ * Best-effort helper that tries to convert a raw column expression into a `ColumnNode`.
+ * This parser is intentionally limited; use it only for simple references or function calls.
+ */
+export const parseRawColumn = (
+  col: string,
+  tableName: string,
+  ctes?: CommonTableExpressionNode[]
+): ColumnNode => {
+  if (col.includes('(')) {
+    const [fn, rest] = col.split('(');
+    const colName = rest.replace(')', '');
+    const [table, name] = colName.includes('.') ? colName.split('.') : [tableName, colName];
+    return { type: 'Column', table, name, alias: col };
+  }
+
+  if (col.includes('.')) {
+    const [potentialCteName, columnName] = col.split('.');
+    const hasCte = ctes?.some(cte => cte.name === potentialCteName);
+
+    if (hasCte) {
+      return { type: 'Column', table: tableName, name: col };
+    }
+
+    return { type: 'Column', table: potentialCteName, name: columnName };
+  }
+
+  return { type: 'Column', table: tableName, name: col };
+};

package/src/utils/relation-alias.ts

@@ -0,0 +1,43 @@
+/**
+ * Separator used when projecting relational columns
+ */
+const RELATION_SEPARATOR = '__';
+
+/**
+ * Parts of a relation alias
+ */
+export interface RelationAliasParts {
+  /**
+   * Relation name (left side of the separator)
+   */
+  relationName: string;
+  /**
+   * Column name (right side of the separator)
+   */
+  columnName: string;
+}
+
+/**
+ * Builds a relation alias from the relation name and column name components.
+ */
+export const makeRelationAlias = (relationName: string, columnName: string): string =>
+  `${relationName}${RELATION_SEPARATOR}${columnName}`;
+
+/**
+ * Parses a relation alias into its relation/column components.
+ * Returns `null` when the alias does not follow the `relation__column` pattern.
+ */
+export const parseRelationAlias = (alias: string): RelationAliasParts | null => {
+  const idx = alias.indexOf(RELATION_SEPARATOR);
+  if (idx === -1) return null;
+  return {
+    relationName: alias.slice(0, idx),
+    columnName: alias.slice(idx + RELATION_SEPARATOR.length)
+  };
+};
+
+/**
+ * Determines whether an alias represents a relation column by checking the `__` convention.
+ */
+export const isRelationAlias = (alias?: string): boolean =>
+  !!alias && alias.includes(RELATION_SEPARATOR);

package/tests/postgres.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { SelectQueryBuilder } from '../src/builder/select';
+import { PostgresDialect } from '../src/dialect/postgres';
+import { Users } from '../src/playground/features/playground/data/schema';
+import { jsonPath, eq } from '../src/ast/expression';
+
+describe('PostgresDialect', () => {
+  it('should compile a simple select', () => {
+    const query = new SelectQueryBuilder(Users).selectRaw('*');
+    const dialect = new PostgresDialect();
+    const compiled = query.compile(dialect);
+    expect(compiled.sql).toBe('SELECT "users"."*" FROM "users";');
+  });
+
+  it('should compile a select with a where clause', () => {
+    const query = new SelectQueryBuilder(Users).selectRaw('*').where(eq(Users.columns.id, 1));
+    const dialect = new PostgresDialect();
+    const compiled = query.compile(dialect);
+    expect(compiled.sql).toBe('SELECT "users"."*" FROM "users" WHERE "users"."id" = ?;');
+    expect(compiled.params).toEqual([1]);
+  });
+
+  it('should compile a select with a json path', () => {
+    const query = new SelectQueryBuilder(Users).selectRaw('*').where(eq(jsonPath(Users.columns.settings, '$.first'), 'John'));
+    const dialect = new PostgresDialect();
+    const compiled = query.compile(dialect);
+    expect(compiled.sql).toBe('SELECT "users"."*" FROM "users" WHERE "users"."settings"->>\'$.first\' = ?;');
+    expect(compiled.params).toEqual(['John']);
+  });
+});

package/tests/window-function.test.ts

@@ -3,6 +3,7 @@ import { SelectQueryBuilder } from '../src/builder/select';
 import { SqliteDialect } from '../src/dialect/sqlite';
 import { MySqlDialect } from '../src/dialect/mysql';
 import { SqlServerDialect } from '../src/dialect/mssql';
+import { PostgresDialect } from '../src/dialect/postgres';
 import { TableDef } from '../src/schema/table';
 import { rowNumber, rank, denseRank, lag, lead, ntile, firstValue, lastValue, windowFunction } from '../src/ast/expression';
 
@@ -14,6 +15,7 @@ describe('Window Function Support', () => {
     const sqlite = new SqliteDialect();
     const mysql = new MySqlDialect();
     const mssql = new SqlServerDialect();
+    const postgres = new PostgresDialect();
 
     it('should generate ROW_NUMBER() window function', () => {
         const users = table('users');
@@ -28,10 +30,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "users"."id" AS "id", "users"."name" AS "name", ROW_NUMBER() OVER () AS "row_num" FROM "users";';
         const expectedMysql = 'SELECT `users`.`id` AS `id`, `users`.`name` AS `name`, ROW_NUMBER() OVER () AS `row_num` FROM `users`;';
         const expectedMssql = 'SELECT [users].[id] AS [id], [users].[name] AS [name], ROW_NUMBER() OVER () AS [row_num] FROM [users];';
+        const expectedPostgres = 'SELECT "users"."id" AS "id", "users"."name" AS "name", ROW_NUMBER() OVER () AS "row_num" FROM "users";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate RANK() with PARTITION BY and ORDER BY', () => {
@@ -48,10 +52,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "orders"."id" AS "id", "orders"."customer_id" AS "customer_id", "orders"."amount" AS "amount", RANK() OVER (PARTITION BY "orders"."customer_id" ORDER BY "orders"."amount" DESC) AS "rank" FROM "orders";';
         const expectedMysql = 'SELECT `orders`.`id` AS `id`, `orders`.`customer_id` AS `customer_id`, `orders`.`amount` AS `amount`, RANK() OVER (PARTITION BY `orders`.`customer_id` ORDER BY `orders`.`amount` DESC) AS `rank` FROM `orders`;';
         const expectedMssql = 'SELECT [orders].[id] AS [id], [orders].[customer_id] AS [customer_id], [orders].[amount] AS [amount], RANK() OVER (PARTITION BY [orders].[customer_id] ORDER BY [orders].[amount] DESC) AS [rank] FROM [orders];';
+        const expectedPostgres = 'SELECT "orders"."id" AS "id", "orders"."customer_id" AS "customer_id", "orders"."amount" AS "amount", RANK() OVER (PARTITION BY "orders"."customer_id" ORDER BY "orders"."amount" DESC) AS "rank" FROM "orders";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate LAG function with offset and default value', () => {
@@ -67,10 +73,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LAG("sales"."amount", ?, ?) OVER () AS "prev_amount" FROM "sales";';
         const expectedMysql = 'SELECT `sales`.`date` AS `date`, `sales`.`amount` AS `amount`, LAG(`sales`.`amount`, ?, ?) OVER () AS `prev_amount` FROM `sales`;';
         const expectedMssql = 'SELECT [sales].[date] AS [date], [sales].[amount] AS [amount], LAG([sales].[amount], @p1, @p2) OVER () AS [prev_amount] FROM [sales];';
+        const expectedPostgres = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LAG("sales"."amount", ?, ?) OVER () AS "prev_amount" FROM "sales";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate LEAD function', () => {
@@ -86,10 +94,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LEAD("sales"."amount", ?) OVER () AS "next_amount" FROM "sales";';
         const expectedMysql = 'SELECT `sales`.`date` AS `date`, `sales`.`amount` AS `amount`, LEAD(`sales`.`amount`, ?) OVER () AS `next_amount` FROM `sales`;';
         const expectedMssql = 'SELECT [sales].[date] AS [date], [sales].[amount] AS [amount], LEAD([sales].[amount], @p1) OVER () AS [next_amount] FROM [sales];';
+        const expectedPostgres = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LEAD("sales"."amount", ?) OVER () AS "next_amount" FROM "sales";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate window function with both PARTITION BY and ORDER BY', () => {
@@ -107,10 +117,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."department" AS "department", "employees"."salary" AS "salary", ROW_NUMBER() OVER (PARTITION BY "employees"."department" ORDER BY "employees"."salary" DESC) AS "dept_rank" FROM "employees";';
         const expectedMysql = 'SELECT `employees`.`id` AS `id`, `employees`.`name` AS `name`, `employees`.`department` AS `department`, `employees`.`salary` AS `salary`, ROW_NUMBER() OVER (PARTITION BY `employees`.`department` ORDER BY `employees`.`salary` DESC) AS `dept_rank` FROM `employees`;';
         const expectedMssql = 'SELECT [employees].[id] AS [id], [employees].[name] AS [name], [employees].[department] AS [department], [employees].[salary] AS [salary], ROW_NUMBER() OVER (PARTITION BY [employees].[department] ORDER BY [employees].[salary] DESC) AS [dept_rank] FROM [employees];';
+        const expectedPostgres = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."department" AS "department", "employees"."salary" AS "salary", ROW_NUMBER() OVER (PARTITION BY "employees"."department" ORDER BY "employees"."salary" DESC) AS "dept_rank" FROM "employees";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate multiple window functions in one query', () => {
@@ -129,9 +141,11 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."salary" AS "salary", ROW_NUMBER() OVER () AS "row_num", RANK() OVER () AS "rank", DENSE_RANK() OVER () AS "dense_rank" FROM "employees";';
         const expectedMysql = 'SELECT `employees`.`id` AS `id`, `employees`.`name` AS `name`, `employees`.`salary` AS `salary`, ROW_NUMBER() OVER () AS `row_num`, RANK() OVER () AS `rank`, DENSE_RANK() OVER () AS `dense_rank` FROM `employees`;';
         const expectedMssql = 'SELECT [employees].[id] AS [id], [employees].[name] AS [name], [employees].[salary] AS [salary], ROW_NUMBER() OVER () AS [row_num], RANK() OVER () AS [rank], DENSE_RANK() OVER () AS [dense_rank] FROM [employees];';
+        const expectedPostgres = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."salary" AS "salary", ROW_NUMBER() OVER () AS "row_num", RANK() OVER () AS "rank", DENSE_RANK() OVER () AS "dense_rank" FROM "employees";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 });