forge-sql-orm 1.0.1

package/scripts/cli.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import dotenv from "dotenv";
+import inquirer from "inquirer";
+import { generateModels } from "./actions/generate-models";
+import { createMigration } from "./actions/migrations-create";
+import { updateMigration } from "./actions/migrations-update";
+import {runPostInstallPatch} from "./actions/PatchPostinstall";
+
+// 🔄 Load environment variables from `.env` file
+dotenv.config();
+
+/**
+ * Prompts the user for missing parameters using Inquirer.js.
+ * @param config - The current configuration object.
+ * @param defaultOutput - Default output path.
+ * @param customAskMissingParams - Optional function for additional prompts.
+ * @returns Updated configuration with user input.
+ */
+const askMissingParams = async (
+  config: any,
+  defaultOutput: string,
+  customAskMissingParams?: (cfg: any, questions: unknown[]) => void,
+) => {
+  const questions: unknown[] = [];
+
+  if (!config.host)
+    questions.push({
+      type: "input",
+      name: "host",
+      message: "Enter database host:",
+      default: "localhost",
+    });
+
+  if (!config.port)
+    questions.push({
+      type: "input",
+      name: "port",
+      message: "Enter database port:",
+      default: "3306",
+      validate: (input: string) => !isNaN(parseInt(input, 10)),
+    });
+
+  if (!config.user)
+    questions.push({
+      type: "input",
+      name: "user",
+      message: "Enter database user:",
+      default: "root",
+    });
+
+  if (!config.password)
+    questions.push({
+      type: "password",
+      name: "password",
+      message: "Enter database password:",
+      mask: "*",
+    });
+
+  if (!config.dbName)
+    questions.push({
+      type: "input",
+      name: "dbName",
+      message: "Enter database name:",
+    });
+
+  if (!config.output)
+    questions.push({
+      type: "input",
+      name: "output",
+      message: "Enter output path:",
+      default: defaultOutput,
+    });
+
+  // Allow additional questions from the caller
+  if (customAskMissingParams) {
+    customAskMissingParams(config, questions);
+  }
+
+  // If there are missing parameters, prompt the user
+  if (questions.length > 0) {
+    // @ts-ignore - Ignore TypeScript warning for dynamic question type
+    const answers = await inquirer.prompt(questions);
+    return { ...config, ...answers, port: parseInt(answers.port, 10) };
+  }
+
+  return config;
+};
+
+/**
+ * Retrieves configuration parameters from command-line arguments and environment variables.
+ * If any required parameters are missing, prompts the user for input.
+ * @param cmd - The command object containing CLI options.
+ * @param defaultOutput - Default output directory.
+ * @param customConfig - Optional function for additional configuration parameters.
+ * @param customAskMissingParams - Optional function for additional prompts.
+ * @returns A fully resolved configuration object.
+ */
+const getConfig = async (
+  cmd: any,
+  defaultOutput: string,
+  customConfig?: () => any,
+  customAskMissingParams?: (cfg: any, questions: unknown[]) => void,
+) => {
+  let config = {
+    host: cmd.host || process.env.FORGE_SQL_ORM_HOST,
+    port: cmd.port
+      ? parseInt(cmd.port, 10)
+      : process.env.FORGE_SQL_ORM_PORT
+        ? parseInt(process.env.FORGE_SQL_ORM_PORT, 10)
+        : undefined,
+    user: cmd.user || process.env.FORGE_SQL_ORM_USER,
+    password: cmd.password || process.env.FORGE_SQL_ORM_PASSWORD,
+    dbName: cmd.dbName || process.env.FORGE_SQL_ORM_DBNAME,
+    output: cmd.output || process.env.FORGE_SQL_ORM_OUTPUT,
+  };
+
+  // Merge additional configurations if provided
+  if (customConfig) {
+    config = { ...config, ...customConfig() };
+  }
+
+  return await askMissingParams(config, defaultOutput, customAskMissingParams);
+};
+
+// 📌 Initialize CLI
+const program = new Command();
+program.version("1.0.0");
+
+// ✅ Command: Generate database models (Entities)
+program
+  .command("generate:model")
+  .description("Generate MikroORM models from the database.")
+  .option("--host <string>", "Database host")
+  .option("--port <number>", "Database port")
+  .option("--user <string>", "Database user")
+  .option("--password <string>", "Database password")
+  .option("--dbName <string>", "Database name")
+  .option("--output <string>", "Output path for entities")
+  .action(async (cmd) => {
+    const config = await getConfig(cmd, "./database/entities");
+    await generateModels(config);
+  });
+
+// ✅ Command: Create initial database migration
+program
+  .command("migrations:create")
+  .description("Generate an initial migration for the entire database.")
+  .option("--host <string>", "Database host")
+  .option("--port <number>", "Database port")
+  .option("--user <string>", "Database user")
+  .option("--password <string>", "Database password")
+  .option("--dbName <string>", "Database name")
+  .option("--output <string>", "Output path for migrations")
+  .option("--entitiesPath <string>", "Path to the folder containing entities")
+  .action(async (cmd) => {
+    const config = await getConfig(
+      cmd,
+      "./database/migration",
+      () => ({
+        entitiesPath: cmd.entitiesPath || process.env.FORGE_SQL_ORM_ENTITIES_PATH,
+      }),
+      (cfg, questions: unknown[]) => {
+        if (!cfg.entitiesPath)
+          questions.push({
+            type: "input",
+            name: "entitiesPath",
+            message: "Enter the path to entities:",
+            default: "./database/entities",
+          });
+      },
+    );
+    await createMigration(config);
+  });
+
+// ✅ Command: Update migration for schema changes
+program
+  .command("migrations:update")
+  .description("Generate a migration to update the database schema.")
+  .option("--host <string>", "Database host")
+  .option("--port <number>", "Database port")
+  .option("--user <string>", "Database user")
+  .option("--password <string>", "Database password")
+  .option("--dbName <string>", "Database name")
+  .option("--output <string>", "Output path for migrations")
+  .option("--entitiesPath <string>", "Path to the folder containing entities")
+  .action(async (cmd) => {
+    const config = await getConfig(
+      cmd,
+      "./database/migration",
+      () => ({
+        entitiesPath: cmd.entitiesPath || process.env.FORGE_SQL_ORM_ENTITIES_PATH,
+      }),
+      (cfg, questions: unknown[]) => {
+        if (!cfg.entitiesPath)
+          questions.push({
+            type: "input",
+            name: "entitiesPath",
+            message: "Enter the path to entities:",
+            default: "./database/entities",
+          });
+      },
+    );
+    await updateMigration(config);
+  });
+
+// Patch MikroORM and Knex
+program
+    .command("patch:mikroorm")
+    .description("Patch MikroORM and Knex dependencies to work properly with Forge")
+    .action(async () => {
+      console.log("Running MikroORM patch...");
+      await runPostInstallPatch();
+      await runPostInstallPatch();
+      await runPostInstallPatch();
+      console.log("✅ MikroORM patch applied successfully!");
+    });
+
+// 🔥 Execute CLI
+program.parse(process.argv);

package/src/core/ForgeSQLCrudOperations.ts

@@ -0,0 +1,164 @@
+import { UpdateQueryResponse, sql } from "@forge/sql";
+import { EntityProperty, EntitySchema } from "..";
+import type { types } from "@mikro-orm/core/types";
+import { transformValue } from "../utils/sqlUtils";
+import { CRUDForgeSQL, ForgeSqlOperation } from "./ForgeSQLQueryBuilder";
+
+export class ForgeSQLCrudOperations implements CRUDForgeSQL {
+  private readonly forgeOperations: ForgeSqlOperation;
+
+  constructor(forgeSqlOperations: ForgeSqlOperation) {
+    this.forgeOperations = forgeSqlOperations;
+  }
+
+  /**
+   * Generates an SQL insert query with values.
+   * @param schema - The entity schema.
+   * @param models - The list of entities to insert.
+   * @param updateIfExists - Whether to update the row if it already exists.
+   * @returns An object containing the SQL query, fields, and values.
+   */
+  private async generateInsertScript<T extends object>(
+    schema: EntitySchema<T>,
+    models: T[],
+    updateIfExists: boolean,
+  ): Promise<{
+    sql: string;
+    fields: string[];
+    values: { type: keyof typeof types; value: unknown }[];
+  }> {
+    const fieldNames: Set<string> = new Set();
+    const fieldValueMaps: Record<string, { type: keyof typeof types; value: unknown }>[] = [];
+
+    models.forEach((model) => {
+      const fieldValueMap: Record<string, { type: keyof typeof types; value: unknown }> = {};
+      schema.meta.props.forEach((p) => {
+        const modelValue = model[p.name];
+        if (p.kind === "scalar" && modelValue !== undefined) {
+          fieldNames.add(p.fieldNames[0] || p.name);
+          fieldValueMap[p.fieldNames[0]] = {
+            type: p.type as keyof typeof types,
+            value: modelValue,
+          };
+        }
+      });
+      fieldValueMaps.push(fieldValueMap);
+    });
+
+    const fields = Array.from(fieldNames);
+    const values = fieldValueMaps.flatMap((fieldValueMap) =>
+      fields.map(
+        (f) =>
+          fieldValueMap[f] || {
+            type: "string",
+            value: null,
+          },
+      ),
+    );
+
+    return {
+      sql: `INSERT INTO ${schema.meta.collection} (${fields.join(",")}) VALUES ${fieldValueMaps
+        .map(
+          (fieldValueMap) =>
+            `(${fields
+              .map((f) =>
+                transformValue(
+                  fieldValueMap[f] || {
+                    type: "string",
+                    value: null,
+                  },
+                ),
+              )
+              .join(",")})`,
+        )
+        .join(
+          ", ",
+        )} ${updateIfExists ? `ON DUPLICATE KEY UPDATE ${fields.map((f) => `${f} = VALUES(${f})`).join(",")}` : ""}`,
+      fields,
+      values,
+    };
+  }
+
+  /**
+   * Inserts records into the database.
+   * @param schema - The entity schema.
+   * @param models - The list of entities to insert.
+   * @param updateIfExists - Whether to update the row if it already exists.
+   * @returns The ID of the inserted row.
+   */
+  async insert<T extends object>(
+    schema: EntitySchema<T>,
+    models: T[],
+    updateIfExists: boolean = false,
+  ): Promise<number> {
+    if (!models || models.length === 0) return 0;
+
+    const query = await this.generateInsertScript(schema, models, updateIfExists);
+    console.debug("INSERT SQL: " + query.sql);
+    console.debug("INSERT VALUES: " + JSON.stringify(query.values));
+    const sqlStatement = sql.prepare<UpdateQueryResponse>(query.sql);
+    const updateQueryResponseResult = await sqlStatement.execute();
+    return updateQueryResponseResult.rows.insertId;
+  }
+
+  /**
+   * Retrieves the primary keys for the given entity schema.
+   * @param schema - The entity schema.
+   * @returns An array of primary key properties.
+   * @throws If no primary keys are found.
+   */
+  private getPrimaryKeys<T extends object>(schema: EntitySchema<T>): EntityProperty<T, unknown>[] {
+    const primaryKeys = schema.meta.props.filter((p) => p.primary);
+    if (!primaryKeys.length) {
+      throw new Error(`No primary keys found for schema: ${schema.meta.className}`);
+    }
+    return primaryKeys;
+  }
+
+  /**
+   * Deletes a record by its ID.
+   * @param id - The ID of the record to delete.
+   * @param schema - The entity schema.
+   * @returns The number of rows affected.
+   * @throws If the entity has more than one primary key.
+   */
+  async deleteById<T extends object>(id: unknown, schema: EntitySchema<T>): Promise<number> {
+    const primaryKeys = this.getPrimaryKeys(schema);
+    if (primaryKeys.length > 1) {
+      throw new Error("Only one primary key is supported");
+    }
+
+    const primaryKey = primaryKeys[0];
+    const queryBuilder = this.forgeOperations.createQueryBuilder(schema.meta.class).delete();
+    queryBuilder.andWhere({ [primaryKey.name]: { $eq: id } });
+
+    const query = queryBuilder.getFormattedQuery();
+    console.debug("DELETE SQL: " + query);
+
+    const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
+    const updateQueryResponseResult = await sqlStatement.execute();
+    return updateQueryResponseResult.rows.affectedRows;
+  }
+
+  /**
+   * Updates a record by its ID.
+   * @param entity - The entity with updated values.
+   * @param schema - The entity schema.
+   * @throws If the primary key value is missing in the entity.
+   */
+  async updateById<T extends object>(entity: T, schema: EntitySchema<T>): Promise<void> {
+    const primaryKeys = this.getPrimaryKeys(schema);
+    const queryBuilder = this.forgeOperations.createQueryBuilder(schema.meta.class).update(entity);
+
+    primaryKeys.forEach((pk) => {
+      const value = entity[pk.name];
+      if (value === null || value === undefined) {
+        throw new Error(`Primary Key ${pk.name} must exist in the model`);
+      }
+      queryBuilder.andWhere({ [pk.name]: { $eq: value } });
+    });
+    const query = queryBuilder.getFormattedQuery();
+    console.debug("UPDATE SQL: " + query);
+    await this.forgeOperations.fetch().executeRawUpdateSQL(query);
+  }
+}

package/src/core/ForgeSQLORM.ts

@@ -0,0 +1,150 @@
+import type { EntityName, LoggingOptions } from "@mikro-orm/core";
+import type { EntitySchema } from "@mikro-orm/core/metadata/EntitySchema";
+import type { AnyEntity, EntityClass, EntityClassGroup } from "@mikro-orm/core/typings";
+import type { QueryBuilder } from "@mikro-orm/knex/query";
+import { MemoryCacheAdapter, MikroORM, NullCacheAdapter } from "@mikro-orm/mysql";
+import { ForgeSQLCrudOperations } from "./ForgeSQLCrudOperations";
+import { CRUDForgeSQL, ForgeSqlOperation, SchemaSqlForgeSql } from "./ForgeSQLQueryBuilder";
+import { ForgeSQLSelectOperations } from "./ForgeSQLSelectOperations";
+import type { Knex } from "knex";
+
+/**
+ * Implementation of ForgeSQLORM that interacts with MikroORM.
+ */
+class ForgeSQLORMImpl implements ForgeSqlOperation {
+  private static instance: ForgeSQLORMImpl | null = null;
+  private readonly mikroORM: MikroORM;
+  private readonly crudOperations: CRUDForgeSQL;
+  private readonly fetchOperations: SchemaSqlForgeSql;
+
+  /**
+   * Private constructor to enforce singleton behavior.
+   * @param entities - The list of entities for ORM initialization.
+   */
+  private constructor(
+    entities: (EntityClass<AnyEntity> | EntityClassGroup<AnyEntity> | EntitySchema)[],
+  ) {
+    console.debug("Initializing ForgeSQLORM...");
+
+    try {
+      this.mikroORM = MikroORM.initSync({
+        dbName: "inmemory",
+        schemaGenerator: {
+          disableForeignKeys: false,
+        },
+        discovery: {
+          warnWhenNoEntities: true,
+        },
+        resultCache: {
+          adapter: NullCacheAdapter,
+        },
+        metadataCache: {
+          enabled: false,
+          adapter: MemoryCacheAdapter,
+        },
+        entities: entities,
+        preferTs: false,
+      });
+
+      this.crudOperations = new ForgeSQLCrudOperations(this);
+      this.fetchOperations = new ForgeSQLSelectOperations();
+    } catch (error) {
+      console.error("ForgeSQLORM initialization failed:", error);
+      throw error; // Prevents inconsistent state
+    }
+  }
+
+  /**
+   * Returns the singleton instance of ForgeSQLORMImpl.
+   * @param entities - List of entities (required only on first initialization).
+   * @returns The singleton instance of ForgeSQLORMImpl.
+   */
+  static getInstance(
+    entities: (EntityClass<AnyEntity> | EntityClassGroup<AnyEntity> | EntitySchema)[],
+  ): ForgeSqlOperation {
+    if (!ForgeSQLORMImpl.instance) {
+      ForgeSQLORMImpl.instance = new ForgeSQLORMImpl(entities);
+    }
+    return ForgeSQLORMImpl.instance;
+  }
+
+  /**
+   * Retrieves the CRUD operations instance.
+   * @returns CRUD operations.
+   */
+  crud(): CRUDForgeSQL {
+    return this.crudOperations;
+  }
+
+  /**
+   * Retrieves the fetch operations instance.
+   * @returns Fetch operations.
+   */
+  fetch(): SchemaSqlForgeSql {
+    return this.fetchOperations;
+  }
+
+  /**
+   * Creates a new query builder for the given entity.
+   * @param entityName - The entity name or an existing query builder.
+   * @param alias - The alias for the entity.
+   * @param loggerContext - Logging options.
+   * @returns The query builder instance.
+   */
+  createQueryBuilder<Entity extends object, RootAlias extends string = never>(
+    entityName: EntityName<Entity> | QueryBuilder<Entity>,
+    alias?: RootAlias,
+    loggerContext?: LoggingOptions,
+  ): QueryBuilder<Entity, RootAlias> {
+    return this.mikroORM.em.createQueryBuilder(entityName, alias, undefined, loggerContext);
+  }
+
+  getKnex(): Knex<any, any[]> {
+    return this.mikroORM.em.getKnex();
+  }
+}
+
+/**
+ * Public class that acts as a wrapper around the private ForgeSQLORMImpl.
+ */
+class ForgeSQLORM {
+  private readonly ormInstance: ForgeSqlOperation;
+
+  constructor(entities: (EntityClass<AnyEntity> | EntityClassGroup<AnyEntity> | EntitySchema)[]) {
+    this.ormInstance = ForgeSQLORMImpl.getInstance(entities);
+  }
+
+  /**
+   * Proxies the `crud` method from `ForgeSQLORMImpl`.
+   * @returns CRUD operations.
+   */
+  crud(): CRUDForgeSQL {
+    return this.ormInstance.crud();
+  }
+
+  /**
+   * Proxies the `fetch` method from `ForgeSQLORMImpl`.
+   * @returns Fetch operations.
+   */
+  fetch(): SchemaSqlForgeSql {
+    return this.ormInstance.fetch();
+  }
+
+  getKnex(): Knex<any, any[]> {
+    return this.ormInstance.getKnex();
+  }
+
+  /**
+   * Proxies the `createQueryBuilder` method from `ForgeSQLORMImpl`.
+   * @returns A new query builder instance.
+   */
+  createQueryBuilder<Entity extends object, RootAlias extends string = never>(
+    entityName: EntityName<Entity> | QueryBuilder<Entity>,
+    alias?: RootAlias,
+    loggerContext?: LoggingOptions,
+  ): QueryBuilder<Entity, RootAlias> {
+    return this.ormInstance.createQueryBuilder(entityName, alias, loggerContext);
+  }
+}
+
+export default ForgeSQLORM;

package/src/core/ForgeSQLQueryBuilder.ts

@@ -0,0 +1,100 @@
+import { UpdateQueryResponse } from "@forge/sql";
+import type { EntityName, LoggingOptions } from "..";
+import type { EntitySchema } from "@mikro-orm/core/metadata/EntitySchema";
+import type { QueryBuilder } from "@mikro-orm/knex/query";
+import type { Knex } from "knex";
+
+/**
+ * Interface representing the main ForgeSQL operations.
+ */
+export interface ForgeSqlOperation extends QueryBuilderForgeSql {
+  /**
+   * Provides CRUD operations.
+   */
+  crud(): CRUDForgeSQL;
+
+  /**
+   * Provides schema-level SQL fetch operations.
+   */
+  fetch(): SchemaSqlForgeSql;
+}
+
+/**
+ * Interface for schema-level SQL operations.
+ */
+export interface SchemaSqlForgeSql {
+  /**
+   * Executes a schema-bound SQL query and maps the result to the specified entity schema.
+   * @param query - The SQL query to execute.
+   * @param schema - The entity schema.
+   * @returns A list of mapped entity objects.
+   */
+  executeSchemaSQL<T extends object>(query: string, schema: EntitySchema<T>): Promise<T[]>;
+
+  /**
+   * Executes a raw SQL query and returns the results.
+   * @param query - The raw SQL query.
+   * @returns A list of results as objects.
+   */
+  executeRawSQL<T extends object | unknown>(query: string): Promise<T[]>;
+
+  /**
+   * Executes a raw SQL update query.
+   * @param query - The raw SQL update query.
+   * @returns The update response containing affected rows.
+   */
+  executeRawUpdateSQL(query: string): Promise<UpdateQueryResponse>;
+}
+
+/**
+ * Interface for CRUD (Create, Read, Update, Delete) operations.
+ */
+export interface CRUDForgeSQL {
+  /**
+   * Inserts multiple records into the database.
+   * @param schema - The entity schema.
+   * @param models - The list of entities to insert.
+   * @param updateIfExists - Whether to update the row if it already exists.
+   * @returns The number of inserted rows.
+   */
+  insert<T extends object>(
+    schema: EntitySchema<T>,
+    models: T[],
+    updateIfExists?: boolean,
+  ): Promise<number>;
+
+  /**
+   * Deletes a record by its ID.
+   * @param id - The ID of the record to delete.
+   * @param schema - The entity schema.
+   * @returns The number of rows affected.
+   */
+  deleteById<T extends object>(id: unknown, schema: EntitySchema<T>): Promise<number>;
+
+  /**
+   * Updates a record by its ID.
+   * @param entity - The entity with updated values.
+   * @param schema - The entity schema.
+   */
+  updateById<T extends object>(entity: T, schema: EntitySchema<T>): Promise<void>;
+}
+
+/**
+ * Interface for Query Builder operations.
+ */
+export interface QueryBuilderForgeSql {
+  /**
+   * Creates a new query builder for the given entity.
+   * @param entityName - The entity name or an existing query builder.
+   * @param alias - The alias for the entity.
+   * @param loggerContext - Logging options.
+   * @returns The query builder instance.
+   */
+  createQueryBuilder<Entity extends object, RootAlias extends string = never>(
+    entityName: EntityName<Entity> | QueryBuilder<Entity>,
+    alias?: RootAlias,
+    loggerContext?: LoggingOptions,
+  ): QueryBuilder<Entity, RootAlias>;
+
+  getKnex(): Knex<any, any[]>;
+}