@engjts/nexus 0.1.0

package/src/database/database.ts

@@ -0,0 +1,70 @@
+import { DatabaseAdapter, MigrationAdapter } from './adapter';
+import { MigrationCLI } from './migrations';
+import { QueryOptimizer, QueryOptimizerOptions } from './optimizer';
+import { QueryBuilder } from './query-builder';
+import { RealtimeConfig, RealtimeDatabase } from './realtime';
+import { SchemaDefinition, TableDefinition, DatabaseOptions, QueryContext } from './types';
+import { TransactionManager } from './transactions';
+
+export interface DatabaseConfig extends DatabaseOptions {
+    optimizer?: QueryOptimizerOptions;
+    realtime?: RealtimeConfig;
+}
+
+export class Database<TSchema extends SchemaDefinition> {
+    private readonly optimizer: QueryOptimizer;
+    private readonly realtime: RealtimeDatabase;
+    private readonly transactions: TransactionManager;
+
+    constructor(
+        private readonly schema: TSchema,
+        private readonly adapter: DatabaseAdapter,
+        options: DatabaseConfig = {}
+    ) {
+        this.optimizer = new QueryOptimizer(schema, options.optimizer);
+        this.realtime = new RealtimeDatabase(options.realtime);
+        this.transactions = new TransactionManager(adapter);
+    }
+
+    table<TName extends keyof TSchema & string>(name: TName): QueryBuilder<TSchema, TName> {
+        const definition = this.getTable(name);
+        return new QueryBuilder<TSchema, TName>({
+            schema: this.schema,
+            table: definition,
+            adapter: this.adapter,
+            optimizer: this.optimizer,
+            realtime: this.realtime
+        });
+    }
+
+    async transaction<T>(callback: (db: this) => Promise<T>, context?: QueryContext) {
+        return this.transactions.run(async () => callback(this), {
+            label: context?.label
+        });
+    }
+
+    migrations(options?: { directory?: string }) {
+        const adapter = this.adapter as MigrationAdapter;
+        if (!('runMigration' in adapter)) {
+            throw new Error('Adapter does not implement migration capabilities');
+        }
+        return new MigrationCLI(adapter, options);
+    }
+
+    realtimeChanges() {
+        return this.realtime;
+    }
+
+    getOptimizer() {
+        return this.optimizer;
+    }
+
+    private getTable<TName extends keyof TSchema & string>(name: TName): TableDefinition {
+        const table = this.schema[name];
+        if (!table) {
+            throw new Error(`Table "${name}" is not registered in the schema`);
+        }
+        return table;
+    }
+}
+

package/src/database/dialect.ts

@@ -0,0 +1,388 @@
+/**
+ * SQL Dialect abstraction for cross-database compatibility.
+ * Handles differences in SQL syntax between MySQL and PostgreSQL.
+ */
+
+export interface SQLDialect {
+    /** Dialect name identifier */
+    readonly name: 'mysql' | 'postgresql' | 'sqlite';
+
+    /** Quote an identifier (table/column name) */
+    quoteIdentifier(identifier: string): string;
+
+    /** Create a parameter placeholder for the given index (1-based) */
+    paramPlaceholder(index: number): string;
+
+    /** Format a LIMIT/OFFSET clause */
+    limitOffset(limit?: number, offset?: number): string;
+
+    /** Format RETURNING clause for INSERT/UPDATE/DELETE */
+    returning(columns?: string[]): string;
+
+    /** Whether the dialect supports RETURNING */
+    supportsReturning: boolean;
+
+    /** Format boolean value */
+    formatBoolean(value: boolean): string;
+
+    /** Format date/timestamp for insertion */
+    formatDate(date: Date): string;
+
+    /** Format JSON value */
+    formatJson(value: unknown): string;
+
+    /** Get current timestamp expression */
+    currentTimestamp(): string;
+
+    /** Get auto-increment column definition */
+    autoIncrement(): string;
+
+    /** Get primary key column type */
+    serialType(): string;
+
+    /** String concatenation operator or function */
+    concat(...parts: string[]): string;
+
+    /** ILIKE or case-insensitive LIKE support */
+    ilike(column: string, pattern: string): string;
+
+    /** JSON extraction operator/function */
+    jsonExtract(column: string, path: string): string;
+
+    /** Upsert (INSERT ... ON CONFLICT/DUPLICATE) syntax */
+    upsert(
+        table: string,
+        columns: string[],
+        values: string[],
+        conflictColumns: string[],
+        updateColumns: string[]
+    ): string;
+}
+
+/**
+ * MySQL Dialect implementation
+ */
+export class MySQLDialect implements SQLDialect {
+    readonly name = 'mysql' as const;
+    readonly supportsReturning = false; // Standard MySQL doesn't support RETURNING
+
+    quoteIdentifier(identifier: string): string {
+        if (identifier.includes('.')) {
+            return identifier
+                .split('.')
+                .map((part) => `\`${part.replace(/`/g, '``')}\``)
+                .join('.');
+        }
+        return `\`${identifier.replace(/`/g, '``')}\``;
+    }
+
+    paramPlaceholder(_index: number): string {
+        return '?';
+    }
+
+    limitOffset(limit?: number, offset?: number): string {
+        const parts: string[] = [];
+        if (limit !== undefined) {
+            parts.push(`LIMIT ${limit}`);
+        }
+        if (offset !== undefined) {
+            // MySQL requires LIMIT when using OFFSET
+            if (limit === undefined) {
+                parts.push('LIMIT 18446744073709551615'); // Max BIGINT
+            }
+            parts.push(`OFFSET ${offset}`);
+        }
+        return parts.join(' ');
+    }
+
+    returning(_columns?: string[]): string {
+        // MySQL doesn't support RETURNING, use LAST_INSERT_ID() instead
+        return '';
+    }
+
+    formatBoolean(value: boolean): string {
+        return value ? '1' : '0';
+    }
+
+    formatDate(date: Date): string {
+        return date.toISOString().slice(0, 19).replace('T', ' ');
+    }
+
+    formatJson(value: unknown): string {
+        return JSON.stringify(value);
+    }
+
+    currentTimestamp(): string {
+        return 'CURRENT_TIMESTAMP';
+    }
+
+    autoIncrement(): string {
+        return 'AUTO_INCREMENT';
+    }
+
+    serialType(): string {
+        return 'INT AUTO_INCREMENT';
+    }
+
+    concat(...parts: string[]): string {
+        return `CONCAT(${parts.join(', ')})`;
+    }
+
+    ilike(column: string, pattern: string): string {
+        // MySQL LIKE is case-insensitive for non-binary strings by default
+        return `${column} LIKE ${pattern}`;
+    }
+
+    jsonExtract(column: string, path: string): string {
+        // MySQL 5.7+ JSON support
+        return `JSON_EXTRACT(${column}, '${path}')`;
+    }
+
+    upsert(
+        table: string,
+        columns: string[],
+        values: string[],
+        _conflictColumns: string[],
+        updateColumns: string[]
+    ): string {
+        const columnList = columns.join(', ');
+        const valueList = values.join(', ');
+        const updateList = updateColumns
+            .map((col) => `${col} = VALUES(${col})`)
+            .join(', ');
+
+        return `INSERT INTO ${table} (${columnList}) VALUES (${valueList}) ON DUPLICATE KEY UPDATE ${updateList}`;
+    }
+}
+
+/**
+ * PostgreSQL Dialect implementation
+ */
+export class PostgreSQLDialect implements SQLDialect {
+    readonly name = 'postgresql' as const;
+    readonly supportsReturning = true;
+
+    quoteIdentifier(identifier: string): string {
+        if (identifier.includes('.')) {
+            return identifier
+                .split('.')
+                .map((part) => `"${part.replace(/"/g, '""')}"`)
+                .join('.');
+        }
+        return `"${identifier.replace(/"/g, '""')}"`;
+    }
+
+    paramPlaceholder(index: number): string {
+        return `$${index}`;
+    }
+
+    limitOffset(limit?: number, offset?: number): string {
+        const parts: string[] = [];
+        if (limit !== undefined) {
+            parts.push(`LIMIT ${limit}`);
+        }
+        if (offset !== undefined) {
+            parts.push(`OFFSET ${offset}`);
+        }
+        return parts.join(' ');
+    }
+
+    returning(columns?: string[]): string {
+        if (!columns || columns.length === 0) {
+            return 'RETURNING *';
+        }
+        return `RETURNING ${columns.join(', ')}`;
+    }
+
+    formatBoolean(value: boolean): string {
+        return value ? 'TRUE' : 'FALSE';
+    }
+
+    formatDate(date: Date): string {
+        return date.toISOString();
+    }
+
+    formatJson(value: unknown): string {
+        return JSON.stringify(value);
+    }
+
+    currentTimestamp(): string {
+        return 'NOW()';
+    }
+
+    autoIncrement(): string {
+        return ''; // PostgreSQL uses SERIAL type instead
+    }
+
+    serialType(): string {
+        return 'SERIAL';
+    }
+
+    concat(...parts: string[]): string {
+        return parts.join(' || ');
+    }
+
+    ilike(column: string, pattern: string): string {
+        return `${column} ILIKE ${pattern}`;
+    }
+
+    jsonExtract(column: string, path: string): string {
+        // PostgreSQL JSONB operators
+        const pathParts = path.split('.');
+        if (pathParts.length === 1) {
+            return `${column}->>'${pathParts[0]}'`;
+        }
+        const intermediatePath = pathParts.slice(0, -1).map((p) => `'${p}'`).join('->');
+        const lastPart = pathParts[pathParts.length - 1];
+        return `${column}->${intermediatePath}->>'${lastPart}'`;
+    }
+
+    upsert(
+        table: string,
+        columns: string[],
+        values: string[],
+        conflictColumns: string[],
+        updateColumns: string[]
+    ): string {
+        const columnList = columns.join(', ');
+        const valueList = values.join(', ');
+        const conflictList = conflictColumns.join(', ');
+        const updateList = updateColumns
+            .map((col) => `${col} = EXCLUDED.${col}`)
+            .join(', ');
+
+        return `INSERT INTO ${table} (${columnList}) VALUES (${valueList}) ON CONFLICT (${conflictList}) DO UPDATE SET ${updateList}`;
+    }
+}
+
+/**
+ * SQLite Dialect implementation (for testing/development)
+ */
+export class SQLiteDialect implements SQLDialect {
+    readonly name = 'sqlite' as const;
+    readonly supportsReturning = true; // SQLite 3.35.0+ supports RETURNING
+
+    quoteIdentifier(identifier: string): string {
+        if (identifier.includes('.')) {
+            return identifier
+                .split('.')
+                .map((part) => `"${part.replace(/"/g, '""')}"`)
+                .join('.');
+        }
+        return `"${identifier.replace(/"/g, '""')}"`;
+    }
+
+    paramPlaceholder(index: number): string {
+        return `?${index}`;
+    }
+
+    limitOffset(limit?: number, offset?: number): string {
+        const parts: string[] = [];
+        if (limit !== undefined) {
+            parts.push(`LIMIT ${limit}`);
+        }
+        if (offset !== undefined) {
+            parts.push(`OFFSET ${offset}`);
+        }
+        return parts.join(' ');
+    }
+
+    returning(columns?: string[]): string {
+        if (!columns || columns.length === 0) {
+            return 'RETURNING *';
+        }
+        return `RETURNING ${columns.join(', ')}`;
+    }
+
+    formatBoolean(value: boolean): string {
+        return value ? '1' : '0';
+    }
+
+    formatDate(date: Date): string {
+        return date.toISOString();
+    }
+
+    formatJson(value: unknown): string {
+        return JSON.stringify(value);
+    }
+
+    currentTimestamp(): string {
+        return "datetime('now')";
+    }
+
+    autoIncrement(): string {
+        return 'AUTOINCREMENT';
+    }
+
+    serialType(): string {
+        return 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    }
+
+    concat(...parts: string[]): string {
+        return parts.join(' || ');
+    }
+
+    ilike(column: string, pattern: string): string {
+        // SQLite LIKE is case-insensitive for ASCII by default
+        return `${column} LIKE ${pattern}`;
+    }
+
+    jsonExtract(column: string, path: string): string {
+        return `json_extract(${column}, '$.${path}')`;
+    }
+
+    upsert(
+        table: string,
+        columns: string[],
+        values: string[],
+        conflictColumns: string[],
+        updateColumns: string[]
+    ): string {
+        const columnList = columns.join(', ');
+        const valueList = values.join(', ');
+        const conflictList = conflictColumns.join(', ');
+        const updateList = updateColumns
+            .map((col) => `${col} = EXCLUDED.${col}`)
+            .join(', ');
+
+        return `INSERT INTO ${table} (${columnList}) VALUES (${valueList}) ON CONFLICT (${conflictList}) DO UPDATE SET ${updateList}`;
+    }
+}
+
+/**
+ * Get dialect instance by name
+ */
+export function getDialect(name: 'mysql' | 'postgresql' | 'sqlite'): SQLDialect {
+    switch (name) {
+        case 'mysql':
+            return new MySQLDialect();
+        case 'postgresql':
+            return new PostgreSQLDialect();
+        case 'sqlite':
+            return new SQLiteDialect();
+        default:
+            throw new Error(`Unknown SQL dialect: ${name}`);
+    }
+}
+
+/**
+ * Detect dialect from adapter name
+ */
+export function detectDialect(adapterName: string): SQLDialect {
+    const normalized = adapterName.toLowerCase();
+    
+    if (normalized.includes('mysql') || normalized.includes('mariadb')) {
+        return new MySQLDialect();
+    }
+    
+    if (normalized.includes('postgres') || normalized.includes('pg')) {
+        return new PostgreSQLDialect();
+    }
+    
+    if (normalized.includes('sqlite')) {
+        return new SQLiteDialect();
+    }
+    
+    // Default to PostgreSQL dialect
+    return new PostgreSQLDialect();
+}

package/src/database/index.ts

@@ -0,0 +1,12 @@
+export * from './types';
+export * from './adapter';
+export * from './schema';
+export * from './query-builder';
+export * from './database';
+export * from './optimizer';
+export * from './transactions';
+export * from './migrations';
+export * from './realtime';
+export * from './dialect';
+export * from './adapters';
+

package/src/database/migrations.ts

@@ -0,0 +1,86 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import path from 'path';
+import { MigrationAdapter } from './adapter';
+
+export interface MigrationFile {
+    id: string;
+    name: string;
+    up: string;
+    down: string;
+}
+
+export interface MigrationCLIOptions {
+    directory?: string;
+}
+
+export class MigrationCLI {
+    private readonly directory: string;
+
+    constructor(private readonly adapter: MigrationAdapter, options: MigrationCLIOptions = {}) {
+        this.directory = options.directory ?? path.join(process.cwd(), 'migrations');
+        mkdirSync(this.directory, { recursive: true });
+    }
+
+    async create(name: string) {
+        const timestamp = this.formatTimestamp(new Date());
+        const filename = `${timestamp}_${name}.sql`;
+        const template = [
+            '-- +up',
+            '-- Write SQL for migrating up here',
+            '',
+            '-- +down',
+            '-- Write SQL for migrating down here'
+        ].join('\n');
+
+        writeFileSync(path.join(this.directory, filename), template, 'utf-8');
+        return filename;
+    }
+
+    list(): string[] {
+        return readdirSync(this.directory)
+            .filter((file) => file.endsWith('.sql'))
+            .sort();
+    }
+
+    private parse(file: string): MigrationFile {
+        const content = readFileSync(path.join(this.directory, file), 'utf-8');
+        const [upSection, downSection] = content.split('-- +down');
+        const up = upSection.replace('-- +up', '').trim();
+        const down = (downSection ?? '').trim();
+        const [id, name] = file.replace('.sql', '').split('_');
+
+        return { id, name, up, down };
+    }
+
+    async up() {
+        await this.adapter.ensureMigrationsTable();
+        for (const file of this.list()) {
+            const migration = this.parse(file);
+            await this.adapter.runMigration(migration.up);
+        }
+    }
+
+    async down(step = 1) {
+        await this.adapter.ensureMigrationsTable();
+        const files = this.list().slice(-step).reverse();
+        for (const file of files) {
+            const migration = this.parse(file);
+            if (!migration.down) {
+                throw new Error(`Migration "${file}" does not define a down section`);
+            }
+            await this.adapter.runMigration(migration.down);
+        }
+    }
+
+    private formatTimestamp(date: Date) {
+        const pad = (value: number) => value.toString().padStart(2, '0');
+        const year = date.getFullYear();
+        const month = pad(date.getMonth() + 1);
+        const day = pad(date.getDate());
+        const hours = pad(date.getHours());
+        const minutes = pad(date.getMinutes());
+        const seconds = pad(date.getSeconds());
+        return `${year}${month}${day}${hours}${minutes}${seconds}`;
+    }
+}
+

package/src/database/optimizer.ts

@@ -0,0 +1,125 @@
+import crypto from 'crypto';
+import { QueryMetrics, SchemaDefinition, TableDefinition } from './types';
+
+export interface OptimizationHint {
+    type: 'n-plus-one' | 'missing-index' | 'slow-query';
+    table: string;
+    message: string;
+    context?: Record<string, unknown>;
+}
+
+interface TrackedQuery {
+    pattern: string;
+    occurrences: number;
+    lastParams?: unknown[];
+    lastTimestamp: number;
+    table: string;
+}
+
+export interface QueryOptimizerOptions {
+    nPlusOneThreshold?: number;
+    slowQueryThresholdMs?: number;
+}
+
+export class QueryOptimizer {
+    private trackedQueries = new Map<string, TrackedQuery>();
+    private hints: OptimizationHint[] = [];
+    private readonly tablesByName: Record<string, TableDefinition>;
+
+    constructor(
+        schema: SchemaDefinition,
+        private readonly options: QueryOptimizerOptions = {}
+    ) {
+        this.tablesByName = schema;
+    }
+
+    analyze(metrics: QueryMetrics): void {
+        this.detectSlowQuery(metrics);
+        this.detectNPlusOne(metrics);
+        this.detectMissingIndexes(metrics);
+    }
+
+    private detectSlowQuery(metrics: QueryMetrics) {
+        const threshold = this.options.slowQueryThresholdMs ?? 25;
+        if (metrics.duration > threshold) {
+            this.hints.push({
+                type: 'slow-query',
+                table: metrics.table,
+                message: `Query exceeded ${threshold}ms (${metrics.duration.toFixed(2)}ms)`,
+                context: { sql: metrics.sql }
+            });
+        }
+    }
+
+    private detectNPlusOne(metrics: QueryMetrics) {
+        const hash = this.hashSql(metrics.sql);
+        const existing = this.trackedQueries.get(hash);
+        const threshold = this.options.nPlusOneThreshold ?? 5;
+
+        if (!existing) {
+            this.trackedQueries.set(hash, {
+                pattern: metrics.sql,
+                occurrences: 1,
+                lastParams: metrics.params,
+                lastTimestamp: Date.now(),
+                table: metrics.table
+            });
+            return;
+        }
+
+        existing.occurrences += 1;
+        existing.lastParams = metrics.params;
+        existing.lastTimestamp = Date.now();
+
+        if (existing.occurrences >= threshold) {
+            this.hints.push({
+                type: 'n-plus-one',
+                table: metrics.table,
+                message: `Potential N+1 detected for query "${metrics.sql.slice(0, 60)}..."`,
+                context: { occurrences: existing.occurrences }
+            });
+            existing.occurrences = 0;
+        }
+    }
+
+    private detectMissingIndexes(metrics: QueryMetrics) {
+        const table = this.tablesByName[metrics.table];
+        if (!table) return;
+
+        const whereMatches = metrics.sql.match(/where\s+([a-zA-Z0-9_." =<>$]+)/i);
+        if (!whereMatches) return;
+
+        const columns = table.indexes.flatMap((idx) => idx.columns);
+        const missingColumns: string[] = [];
+
+        whereMatches[1]
+            .split(/\s+and\s+/i)
+            .map((condition) => condition.trim().replace(/["`]/g, ''))
+            .forEach((condition) => {
+                const column = condition.split(/\s+/)[0];
+                if (!columns.includes(column)) {
+                    missingColumns.push(column);
+                }
+            });
+
+        if (missingColumns.length > 0) {
+            this.hints.push({
+                type: 'missing-index',
+                table: table.name,
+                message: `Consider adding index on columns: ${missingColumns.join(', ')}`,
+                context: { whereClause: whereMatches[0] }
+            });
+        }
+    }
+
+    consumeHints(): OptimizationHint[] {
+        const hints = [...this.hints];
+        this.hints.length = 0;
+        return hints;
+    }
+
+    private hashSql(sql: string): string {
+        return crypto.createHash('sha1').update(sql).digest('hex');
+    }
+}
+