metal-orm 1.0.1 → 1.0.3

package/docs/api-reference.md

@@ -0,0 +1,22 @@
+# API Reference
+
+This section provides a reference for the core classes, key functions, and utility functions in MetalORM.
+
+### Core Classes
+- `SelectQueryBuilder` - Main query builder class
+- `MySqlDialect` / `SQLiteDialect` / `MSSQLDialect` - SQL dialect compilers
+- `HydrationManager` - Handles relation hydration logic
+
+### Key Functions
+- `defineTable()` - Define database tables
+- `col.*()` - Column type definitions
+- `hasMany()` / `belongsTo()` - Relation definitions
+- `eq()`, `and()`, `or()`, etc. - Expression builders
+- `hydrateRows()` - Transform flat rows to nested objects
+
+### Utility Functions
+- `count()`, `sum()`, `avg()` - Aggregate functions
+- `like()`, `between()`, `inList()`, `notInList()` - Comparison operators
+- `jsonPath()` - JSON extraction
+- `caseWhen()`, `exists()`, `notExists()` - Conditional and subquery helpers
+- `rowNumber()`, `rank()`, `denseRank()`, `lag()`, `lead()`, `windowFunction()` - Window function helpers

package/docs/getting-started.md

@@ -0,0 +1,104 @@
+# Getting Started
+
+This guide will help you get started with MetalORM.
+
+## Installation
+
+You can install MetalORM using npm, yarn, or pnpm:
+
+```bash
+# npm
+npm install metal-orm
+
+# yarn
+yarn add metal-orm
+
+# pnpm
+pnpm add metal-orm
+```
+
+## Quick Start
+
+Here's a complete example to get you started:
+
+```typescript
+import {
+  defineTable,
+  col,
+  hasMany,
+  SelectQueryBuilder,
+  eq,
+  count,
+  hydrateRows,
+  MySqlDialect
+} from 'metal-orm';
+
+// 1. Define your schema
+const posts = defineTable(
+  'posts',
+  {
+    id: col.int().primaryKey(),
+    title: col.varchar(255).notNull(),
+    content: col.text(),
+    userId: col.int().notNull(),
+    createdAt: col.timestamp().default('CURRENT_TIMESTAMP'),
+    updatedAt: col.timestamp()
+  }
+);
+
+const users = defineTable(
+  'users',
+  {
+    id: col.int().primaryKey(),
+    name: col.varchar(255).notNull(),
+    email: col.varchar(255).unique(),
+    createdAt: col.timestamp().default('CURRENT_TIMESTAMP')
+  },
+  {
+    posts: hasMany(posts, 'userId')
+  }
+);
+
+// 2. Build your query
+const builder = new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    name: users.columns.name,
+    email: users.columns.email,
+    totalPosts: count(posts.columns.id)
+  })
+  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
+  .groupBy(users.columns.id, users.columns.name, users.columns.email)
+  .orderBy(count(posts.columns.id), 'DESC')
+  .limit(20)
+  .include('posts', {
+    columns: [posts.columns.id, posts.columns.title, posts.columns.createdAt]
+  });
+
+// 3. Compile to SQL
+const dialect = new MySqlDialect();
+const { sql, params } = builder.compile(dialect);
+
+// 4. Execute and hydrate
+const rows = await connection.execute(sql, params);
+const hydrated = hydrateRows(rows, builder.getHydrationPlan());
+
+console.log(hydrated);
+// [
+//   {
+//     id: 1,
+//     name: 'John Doe',
+//     email: 'john@example.com',
+//     totalPosts: 15,
+//     posts: [
+//       {
+//         id: 101,
+//         title: 'Latest Post',
+//         createdAt: '2023-05-15T10:00:00.000Z'
+//       },
+//       // ... more posts
+//     ]
+//   }
+//   // ... more users
+// ]
+```

package/docs/hydration.md

@@ -0,0 +1,41 @@
+# Relation Hydration
+
+MetalORM can automatically transform flat database rows into nested JavaScript objects, making it easy to work with relational data.
+
+## Hydrating Results
+
+The `hydrateRows()` function takes an array of database rows and a hydration plan to produce nested objects. The hydration plan is generated by the `SelectQueryBuilder` when you use the `include()` method.
+
+```typescript
+const builder = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .include('posts', {
+    columns: ['id', 'title', 'content'],
+    include: {
+      comments: {
+        columns: ['id', 'content', 'createdAt']
+      }
+    }
+  });
+
+const { sql, params } = builder.compile(new MySqlDialect());
+const rows = await db.execute(sql, params);
+
+// Automatically hydrates to:
+// {
+//   id: 1,
+//   name: 'John',
+//   posts: [
+//     {
+//       id: 1,
+//       title: 'First Post',
+//       comments: [...]
+//     }
+//   ]
+// }
+const hydrated = hydrateRows(rows, builder.getHydrationPlan());
+```
+
+## How it Works
+
+The `SelectQueryBuilder` analyzes the `include()` configuration and generates a `HydrationPlan`. This plan contains the necessary information to map the flat rows to a nested structure, including relation details and column aliases. The `hydrateRows()` function then uses this plan to efficiently process the result set.

package/docs/index.md

@@ -0,0 +1,31 @@
+# Introduction to MetalORM
+
+MetalORM is a TypeScript-first SQL query builder designed for developers who want the power of raw SQL with the convenience of a modern ORM. It keeps SQL generation deterministic (CTEs, aggregates, window functions, EXISTS/subqueries) while letting you introspect the AST or reuse builders inside larger queries.
+
+## Philosophy
+
+MetalORM follows these core principles:
+
+- **Type Safety First**: Leverage TypeScript to catch errors at compile time
+- **SQL Transparency**: Generate predictable, readable SQL that you can inspect
+- **Composition Over Configuration**: Build complex queries by composing simple parts
+- **Zero Magic**: Explicit operations with clear AST representation
+- **Multi-Dialect Support**: Write once, compile to MySQL, SQLite, or SQL Server
+
+## Features
+
+- **Declarative Schema Definition**: Define your database structure in TypeScript with full type inference.
+- **Rich Query Building**: A fluent API to build simple and complex queries.
+- **Advanced SQL Features**: Support for CTEs, window functions, subqueries, and more.
+- **Relation Hydration**: Automatically transform flat database rows into nested JavaScript objects.
+- **Multi-Dialect Support**: Compile the same query to different SQL dialects.
+
+## Table of Contents
+
+- [Getting Started](./getting-started.md)
+- [Schema Definition](./schema-definition.md)
+- [Query Builder](./query-builder.md)
+- [Advanced Features](./advanced-features.md)
+- [Hydration](./hydration.md)
+- [Multi-Dialect Support](./multi-dialect-support.md)
+- [API Reference](./api-reference.md)

package/docs/multi-dialect-support.md

@@ -0,0 +1,34 @@
+# Multi-Dialect Support
+
+MetalORM is designed to be database-agnostic. You can write your queries once and compile them to different SQL dialects.
+
+## Compiling Queries
+
+The `compile()` method on the `SelectQueryBuilder` takes a dialect instance and returns the compiled SQL and parameters.
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .where(eq(users.columns.id, 1))
+  .limit(10);
+
+// MySQL
+const mysql = query.compile(new MySqlDialect());
+// SQL: SELECT * FROM users WHERE id = ? LIMIT ?
+
+// SQLite
+const sqlite = query.compile(new SQLiteDialect());
+// SQL: SELECT * FROM users WHERE id = ? LIMIT ?
+
+// SQL Server
+const mssql = query.compile(new MSSQLDialect());
+// SQL: SELECT TOP 10 * FROM users WHERE id = @p1
+```
+
+## Supported Dialects
+
+- **MySQL**: `MySqlDialect`
+- **SQLite**: `SQLiteDialect`
+- **SQL Server**: `MSSQLDialect`
+
+Each dialect handles the specific syntax and parameterization of the target database.

package/docs/query-builder.md

@@ -0,0 +1,75 @@
+# Query Builder
+
+MetalORM's query builder provides a fluent and expressive API for constructing SQL queries.
+
+## Selecting Data
+
+The `SelectQueryBuilder` is the main entry point for building `SELECT` queries.
+
+### Basic Selections
+
+You can select all columns using `selectRaw('*')` or specify columns using `select()`:
+
+```typescript
+// Select all columns
+const query = new SelectQueryBuilder(users).selectRaw('*');
+
+// Select specific columns
+const query = new SelectQueryBuilder(users).select({
+  id: users.columns.id,
+  name: users.columns.name,
+});
+```
+
+### Joins
+
+You can join tables using `leftJoin`, `innerJoin`, `rightJoin`, etc.
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .select({
+    userId: users.columns.id,
+    postTitle: posts.columns.title,
+  })
+  .leftJoin(posts, eq(posts.columns.userId, users.columns.id));
+```
+
+### Filtering
+
+You can filter results using the `where()` method with expression helpers:
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .where(and(
+    like(users.columns.name, '%John%'),
+    gt(users.columns.createdAt, new Date('2023-01-01'))
+  ));
+```
+
+### Aggregation
+
+You can use aggregate functions like `count()`, `sum()`, `avg()`, etc., and group the results.
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .select({
+    userId: users.columns.id,
+    postCount: count(posts.columns.id),
+  })
+  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
+  .groupBy(users.columns.id)
+  .having(gt(count(posts.columns.id), 5));
+```
+
+### Ordering and Pagination
+
+You can order the results using `orderBy()` and paginate using `limit()` and `offset()`.
+
+```typescript
+const query = new SelectQueryBuilder(posts)
+  .selectRaw('*')
+  .orderBy(posts.columns.createdAt, 'DESC')
+  .limit(10)
+  .offset(20);
+```

package/docs/schema-definition.md

@@ -0,0 +1,61 @@
+# Schema Definition
+
+MetalORM allows you to define your database schema in TypeScript, providing full type inference and a single source of truth for your data structures.
+
+## Defining Tables
+
+You can define a table using the `defineTable` function. It takes the table name, a columns object, and an optional relations object.
+
+```typescript
+import { defineTable, col } from 'metal-orm';
+
+const users = defineTable('users', {
+  id: col.int().primaryKey(),
+  name: col.varchar(255).notNull(),
+  email: col.varchar(255).unique(),
+  createdAt: col.timestamp().default('CURRENT_TIMESTAMP'),
+});
+```
+
+## Column Types
+
+MetalORM provides a variety of column types through the `col` object:
+
+- `col.int()`: Integer
+- `col.varchar(length)`: Variable-length string
+- `col.text()`: Text
+- `col.timestamp()`: Timestamp
+- `col.json()`: JSON
+- ...and more.
+
+You can also chain modifiers to define column constraints:
+
+- `.primaryKey()`: Marks the column as a primary key.
+- `.notNull()`: Adds a `NOT NULL` constraint.
+- `.unique()`: Adds a `UNIQUE` constraint.
+- `.default(value)`: Sets a default value.
+
+## Relations
+
+You can define relations between tables using `hasMany` and `belongsTo`:
+
+```typescript
+import { defineTable, col, hasMany } from 'metal-orm';
+
+const posts = defineTable('posts', {
+  id: col.int().primaryKey(),
+  title: col.varchar(255).notNull(),
+  userId: col.int().notNull(),
+});
+
+const users = defineTable(
+  'users',
+  {
+    id: col.int().primaryKey(),
+    name: col.varchar(255).notNull(),
+  },
+  {
+    posts: hasMany(posts, 'userId'),
+  }
+);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "exports": {
     ".": {