@promakeai/orm 1.0.0

package/src/utils/populateResolver.ts

@@ -0,0 +1,322 @@
+/**
+ * Populate Resolver
+ *
+ * Resolves references (foreign keys) in query results using batch fetching
+ * to avoid N+1 query problems.
+ *
+ * @example
+ * ```typescript
+ * const products = await orm.list('products', {
+ *   populate: ['categoryId', 'brandId']
+ * });
+ * // Each product now has .category and .brand objects
+ *
+ * // Nested populate with options
+ * const orders = await orm.list('orders', {
+ *   populate: {
+ *     userId: true,
+ *     items: {
+ *       populate: { productId: true },
+ *       limit: 10
+ *     }
+ *   }
+ * });
+ * ```
+ */
+
+import type {
+  SchemaDefinition,
+  TableDefinition,
+  FieldDefinition,
+  PopulateOption,
+  PopulateNested,
+} from "../types";
+
+/**
+ * Adapter interface for fetching records
+ * Minimal interface needed by populate resolver
+ */
+export interface PopulateAdapter {
+  findMany<T = unknown>(
+    table: string,
+    options?: { where?: Record<string, unknown> }
+  ): Promise<T[]>;
+}
+
+/**
+ * Resolved reference info
+ */
+interface ResolvedRef {
+  table: string;
+  field: string;
+  localField: string;
+  targetField: string;
+  isArray: boolean;
+}
+
+/**
+ * Normalized populate entry
+ */
+interface NormalizedPopulateEntry {
+  fieldName: string;
+  options?: PopulateNested;
+}
+
+/**
+ * Get reference info from field definition
+ */
+function getRefInfo(
+  fieldName: string,
+  field: FieldDefinition
+): ResolvedRef | null {
+  if (!field.ref) return null;
+
+  const ref = field.ref;
+  const isString = typeof ref === "string";
+
+  return {
+    table: isString ? ref : ref.table,
+    field: isString ? "id" : ref.field || "id",
+    localField: fieldName,
+    targetField: isString ? "id" : ref.field || "id",
+    isArray: Array.isArray(field.default) || fieldName.endsWith("Ids"),
+  };
+}
+
+/**
+ * Convert field name to populated property name
+ * categoryId -> category
+ * tagIds -> tags
+ * user_id -> user
+ */
+function toPopulatedName(fieldName: string): string {
+  // Handle array refs: tagIds -> tags
+  if (fieldName.endsWith("Ids")) {
+    return fieldName.slice(0, -3) + "s";
+  }
+  // Handle singular refs: categoryId -> category, user_id -> user
+  if (fieldName.endsWith("Id")) {
+    return fieldName.slice(0, -2);
+  }
+  if (fieldName.endsWith("_id")) {
+    return fieldName.slice(0, -3);
+  }
+  return fieldName;
+}
+
+/**
+ * Extract unique values from records for a given field
+ */
+function extractUniqueValues<T>(
+  records: T[],
+  fieldName: string
+): (string | number)[] {
+  const values = new Set<string | number>();
+
+  for (const record of records) {
+    const value = (record as Record<string, unknown>)[fieldName];
+    if (value == null) continue;
+
+    if (Array.isArray(value)) {
+      for (const v of value) {
+        if (v != null) values.add(v as string | number);
+      }
+    } else {
+      values.add(value as string | number);
+    }
+  }
+
+  return Array.from(values);
+}
+
+/**
+ * Create lookup map from records by field
+ */
+function createLookupMap<T>(
+  records: T[],
+  keyField: string
+): Map<string | number, T> {
+  const map = new Map<string | number, T>();
+  for (const record of records) {
+    const key = (record as Record<string, unknown>)[keyField];
+    if (key != null) {
+      map.set(key as string | number, record);
+    }
+  }
+  return map;
+}
+
+/**
+ * Normalize populate option to array of entries
+ */
+function normalizePopulate(
+  populate: PopulateOption | undefined
+): NormalizedPopulateEntry[] {
+  if (!populate) return [];
+
+  // String: "userId categoryIds" -> ["userId", "categoryIds"]
+  if (typeof populate === "string") {
+    return populate.split(/\s+/).map((fieldName) => ({ fieldName }));
+  }
+
+  // Array: ["userId", "categoryIds"]
+  if (Array.isArray(populate)) {
+    return populate.map((fieldName) => ({ fieldName }));
+  }
+
+  // Object: { userId: true, categoryIds: { populate: ... } }
+  const entries: NormalizedPopulateEntry[] = [];
+  for (const [fieldName, value] of Object.entries(populate)) {
+    if (value === true) {
+      entries.push({ fieldName });
+    } else if (value && typeof value === "object") {
+      entries.push({ fieldName, options: value as PopulateNested });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Resolve populated references for query results
+ *
+ * @param records - Query results to populate
+ * @param table - Table name of the records
+ * @param populate - Fields to populate
+ * @param schema - Schema definition
+ * @param adapter - Data adapter for fetching
+ * @returns Records with populated references
+ */
+export async function resolvePopulate<T>(
+  records: T[],
+  table: string,
+  populate: PopulateOption | undefined,
+  schema: SchemaDefinition,
+  adapter: PopulateAdapter
+): Promise<T[]> {
+  if (!records.length) return records;
+
+  const populateEntries = normalizePopulate(populate);
+  if (!populateEntries.length) return records;
+
+  const tableDef = schema.tables[table];
+  if (!tableDef) return records;
+
+  // Process each populate entry
+  for (const entry of populateEntries) {
+    const { fieldName, options } = entry;
+
+    const field = tableDef.fields[fieldName];
+    if (!field) continue;
+
+    const refInfo = getRefInfo(fieldName, field);
+    if (!refInfo) continue;
+
+    // Extract unique foreign key values
+    const fkValues = extractUniqueValues(records, fieldName);
+    if (!fkValues.length) continue;
+
+    // Batch fetch referenced records
+    const refRecords = await adapter.findMany(refInfo.table, {
+      where: { [refInfo.targetField]: { $in: fkValues } },
+    });
+
+    // Recursively populate nested references
+    let populatedRefRecords = refRecords;
+    if (options?.populate) {
+      populatedRefRecords = await resolvePopulate(
+        refRecords,
+        refInfo.table,
+        options.populate,
+        schema,
+        adapter
+      );
+    }
+
+    // Create lookup map
+    const lookupMap = createLookupMap(populatedRefRecords, refInfo.targetField);
+
+    // Attach populated data to records
+    const populatedName = toPopulatedName(fieldName);
+
+    for (const record of records) {
+      const fkValue = (record as Record<string, unknown>)[fieldName];
+
+      if (fkValue == null) {
+        (record as Record<string, unknown>)[populatedName] = null;
+        continue;
+      }
+
+      if (refInfo.isArray && Array.isArray(fkValue)) {
+        // Array reference: tagIds -> tags[]
+        (record as Record<string, unknown>)[populatedName] = fkValue
+          .map((v: unknown) => lookupMap.get(v as string | number))
+          .filter(Boolean);
+      } else {
+        // Single reference: categoryId -> category
+        (record as Record<string, unknown>)[populatedName] =
+          lookupMap.get(fkValue as string | number) || null;
+      }
+    }
+  }
+
+  return records;
+}
+
+/**
+ * Get all populatable fields from a table
+ */
+export function getPopulatableFields(tableDef: TableDefinition): string[] {
+  return Object.entries(tableDef.fields)
+    .filter(([_, field]) => field.ref != null)
+    .map(([name]) => name);
+}
+
+/**
+ * Validate populate options against schema
+ */
+export function validatePopulate(
+  populate: PopulateOption | undefined,
+  table: string,
+  schema: SchemaDefinition
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const populateEntries = normalizePopulate(populate);
+
+  const tableDef = schema.tables[table];
+  if (!tableDef) {
+    errors.push(`Table '${table}' not found in schema`);
+    return { valid: false, errors };
+  }
+
+  for (const entry of populateEntries) {
+    const { fieldName, options } = entry;
+    const field = tableDef.fields[fieldName];
+
+    if (!field) {
+      errors.push(`Field '${fieldName}' not found in table '${table}'`);
+      continue;
+    }
+
+    if (!field.ref) {
+      errors.push(
+        `Field '${fieldName}' in table '${table}' is not a reference field`
+      );
+      continue;
+    }
+
+    // Validate nested populate
+    if (options?.populate) {
+      const refInfo = getRefInfo(fieldName, field);
+      if (refInfo) {
+        const nestedValidation = validatePopulate(
+          options.populate,
+          refInfo.table,
+          schema
+        );
+        errors.push(...nestedValidation.errors);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/utils/translationQuery.ts

@@ -0,0 +1,306 @@
+/**
+ * Translation Query Builder
+ *
+ * Build SQL queries with automatic translation table joins
+ * and COALESCE for language fallback.
+ */
+
+import type { SchemaDefinition, TableDefinition, OrderByOption } from "../types";
+import {
+  getTranslatableFields,
+  hasTranslatableFields,
+} from "../schema/schemaHelpers";
+import {
+  singularize,
+  toTranslationTableName,
+  toTranslationFKName,
+} from "../schema/helpers";
+import { buildWhereClause, type WhereResult } from "./whereBuilder";
+
+/**
+ * Build WHERE clause with optional table alias prefix
+ */
+function buildAliasedWhereClause(
+  where: Record<string, unknown>,
+  alias?: string
+): WhereResult {
+  const result = buildWhereClause(where);
+
+  if (!alias || !result.sql) {
+    return result;
+  }
+
+  let sql = result.sql;
+  const fields = Object.keys(where).filter((k) => !k.startsWith("$"));
+
+  for (const field of fields) {
+    const regex = new RegExp(`\\b${field}\\b(?!\\.)`, "g");
+    sql = sql.replace(regex, `${alias}.${field}`);
+  }
+
+  return { sql, params: result.params };
+}
+
+/**
+ * Options for translation queries
+ */
+export interface TranslationQueryOptions {
+  table: string;
+  schema: SchemaDefinition;
+  lang: string;
+  fallbackLang?: string;
+  where?: Record<string, unknown>;
+  orderBy?: OrderByOption[];
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Query result with SQL and parameters
+ */
+export interface TranslationQueryResult {
+  sql: string;
+  params: unknown[];
+}
+
+/**
+ * Build SELECT query with translation joins
+ */
+export function buildTranslationQuery(
+  options: TranslationQueryOptions
+): TranslationQueryResult {
+  const {
+    table,
+    schema,
+    lang,
+    fallbackLang = schema.languages.default,
+    where,
+    orderBy,
+    limit,
+    offset,
+  } = options;
+
+  const tableSchema = schema.tables[table];
+  if (!tableSchema) {
+    throw new Error(`Table not found in schema: ${table}`);
+  }
+
+  const translatableFields = getTranslatableFields(tableSchema);
+
+  if (translatableFields.length === 0) {
+    return buildSimpleQuery(table, { where, orderBy, limit, offset });
+  }
+
+  const transTable = toTranslationTableName(table);
+  const fkName = toTranslationFKName(table);
+
+  const mainAlias = "m";
+  const transAlias = "t";
+  const fallbackAlias = "fb";
+
+  // Build SELECT fields
+  const selectFields: string[] = [];
+
+  for (const [fieldName, field] of Object.entries(tableSchema.fields)) {
+    if (field.translatable) {
+      selectFields.push(
+        `COALESCE(${transAlias}.${fieldName}, ${fallbackAlias}.${fieldName}) as ${fieldName}`
+      );
+    } else {
+      selectFields.push(`${mainAlias}.${fieldName}`);
+    }
+  }
+
+  let sql = `SELECT ${selectFields.join(", ")}
+FROM ${table} ${mainAlias}
+LEFT JOIN ${transTable} ${transAlias}
+  ON ${mainAlias}.id = ${transAlias}.${fkName}
+  AND ${transAlias}.language_code = ?
+LEFT JOIN ${transTable} ${fallbackAlias}
+  ON ${mainAlias}.id = ${fallbackAlias}.${fkName}
+  AND ${fallbackAlias}.language_code = ?`;
+
+  const params: unknown[] = [lang, fallbackLang];
+
+  if (where && Object.keys(where).length > 0) {
+    const whereResult = buildAliasedWhereClause(where, mainAlias);
+    sql += `\nWHERE ${whereResult.sql}`;
+    params.push(...whereResult.params);
+  }
+
+  if (orderBy && orderBy.length > 0) {
+    const orderClauses = orderBy.map((o) => {
+      if (translatableFields.includes(o.field)) {
+        return `COALESCE(${transAlias}.${o.field}, ${fallbackAlias}.${o.field}) ${o.direction}`;
+      }
+      return `${mainAlias}.${o.field} ${o.direction}`;
+    });
+    sql += `\nORDER BY ${orderClauses.join(", ")}`;
+  }
+
+  if (limit !== undefined) {
+    sql += `\nLIMIT ?`;
+    params.push(limit);
+  }
+
+  if (offset !== undefined) {
+    sql += `\nOFFSET ?`;
+    params.push(offset);
+  }
+
+  return { sql, params };
+}
+
+/**
+ * Build query for single record by ID with translations
+ */
+export function buildTranslationQueryById(
+  table: string,
+  schema: SchemaDefinition,
+  id: number | string,
+  lang: string,
+  fallbackLang?: string
+): TranslationQueryResult {
+  return buildTranslationQuery({
+    table,
+    schema,
+    lang,
+    fallbackLang,
+    where: { id },
+    limit: 1,
+  });
+}
+
+/**
+ * Build simple query without translations
+ */
+function buildSimpleQuery(
+  table: string,
+  options: {
+    where?: Record<string, unknown>;
+    orderBy?: OrderByOption[];
+    limit?: number;
+    offset?: number;
+  }
+): TranslationQueryResult {
+  let sql = `SELECT * FROM ${table}`;
+  const params: unknown[] = [];
+
+  if (options.where && Object.keys(options.where).length > 0) {
+    const whereResult = buildWhereClause(options.where);
+    sql += ` WHERE ${whereResult.sql}`;
+    params.push(...whereResult.params);
+  }
+
+  if (options.orderBy && options.orderBy.length > 0) {
+    const orderClauses = options.orderBy.map((o) => `${o.field} ${o.direction}`);
+    sql += ` ORDER BY ${orderClauses.join(", ")}`;
+  }
+
+  if (options.limit !== undefined) {
+    sql += ` LIMIT ?`;
+    params.push(options.limit);
+  }
+
+  if (options.offset !== undefined) {
+    sql += ` OFFSET ?`;
+    params.push(options.offset);
+  }
+
+  return { sql, params };
+}
+
+/**
+ * Build INSERT statement for translation
+ */
+export function buildTranslationInsert(
+  table: string,
+  schema: SchemaDefinition,
+  recordId: number | string,
+  lang: string,
+  data: Record<string, unknown>
+): TranslationQueryResult {
+  const tableSchema = schema.tables[table];
+  if (!tableSchema) {
+    throw new Error(`Table not found in schema: ${table}`);
+  }
+
+  const translatableFields = getTranslatableFields(tableSchema);
+  const transTable = toTranslationTableName(table);
+  const fkName = toTranslationFKName(table);
+
+  const fields = [fkName, "language_code"];
+  const values: unknown[] = [recordId, lang];
+
+  for (const field of translatableFields) {
+    if (data[field] !== undefined) {
+      fields.push(field);
+      values.push(data[field]);
+    }
+  }
+
+  const placeholders = fields.map(() => "?").join(", ");
+  const sql = `INSERT INTO ${transTable} (${fields.join(", ")}) VALUES (${placeholders})`;
+
+  return { sql, params: values };
+}
+
+/**
+ * Build UPSERT statement for translation (INSERT OR REPLACE)
+ */
+export function buildTranslationUpsert(
+  table: string,
+  schema: SchemaDefinition,
+  recordId: number | string,
+  lang: string,
+  data: Record<string, unknown>
+): TranslationQueryResult {
+  const tableSchema = schema.tables[table];
+  if (!tableSchema) {
+    throw new Error(`Table not found in schema: ${table}`);
+  }
+
+  const translatableFields = getTranslatableFields(tableSchema);
+  const transTable = toTranslationTableName(table);
+  const fkName = toTranslationFKName(table);
+
+  const fields = [fkName, "language_code"];
+  const values: unknown[] = [recordId, lang];
+
+  for (const field of translatableFields) {
+    if (data[field] !== undefined) {
+      fields.push(field);
+      values.push(data[field]);
+    }
+  }
+
+  const placeholders = fields.map(() => "?").join(", ");
+  const sql = `INSERT OR REPLACE INTO ${transTable} (${fields.join(", ")}) VALUES (${placeholders})`;
+
+  return { sql, params: values };
+}
+
+/**
+ * Extract translatable fields from data object
+ */
+export function extractTranslatableData(
+  data: Record<string, unknown>,
+  tableSchema: TableDefinition
+): {
+  mainData: Record<string, unknown>;
+  translatableData: Record<string, unknown>;
+} {
+  const translatableFields = getTranslatableFields(tableSchema);
+  const mainData: Record<string, unknown> = {};
+  const translatableData: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(data)) {
+    if (translatableFields.includes(key)) {
+      translatableData[key] = value;
+    } else if (key !== "translations") {
+      mainData[key] = value;
+    }
+  }
+
+  return { mainData, translatableData };
+}