@promakeai/orm 1.0.0

package/dist/utils/whereBuilder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MongoDB-style Where Clause Builder
+ *
+ * Converts MongoDB/Mongoose-style query objects into SQL WHERE clauses
+ * with parameterized values.
+ *
+ * Supported operators:
+ * - Comparison: $eq, $ne, $gt, $gte, $lt, $lte
+ * - Array: $in, $nin
+ * - String: $like, $notLike
+ * - Range: $between
+ * - Null: $isNull
+ * - Negation: $not (field-level)
+ * - Logical: $and, $or, $nor
+ */
+export interface WhereResult {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Build a SQL WHERE clause from a MongoDB-style query object.
+ *
+ * @example
+ * // Simple equality
+ * buildWhereClause({ active: 1 })
+ * // => { sql: "active = ?", params: [1] }
+ *
+ * @example
+ * // Comparison operators
+ * buildWhereClause({ age: { $gte: 18, $lt: 65 } })
+ * // => { sql: "(age >= ? AND age < ?)", params: [18, 65] }
+ *
+ * @example
+ * // Logical operators
+ * buildWhereClause({ $or: [{ active: 1 }, { role: "admin" }] })
+ * // => { sql: "(active = ? OR role = ?)", params: [1, "admin"] }
+ */
+export declare function buildWhereClause(where?: Record<string, unknown>): WhereResult;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@promakeai/orm",
+  "version": "1.0.0",
+  "description": "Database-agnostic ORM core - works in browser and Node.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target browser --format esm && bun x tsc --emitDeclarationOnly",
+    "dev": "bun build src/index.ts --outdir dist --target browser --format esm --watch",
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "orm",
+    "database",
+    "adapter",
+    "typescript",
+    "browser",
+    "nodejs",
+    "sql",
+    "nosql",
+    "rest"
+  ],
+  "author": "Promake Inc.",
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/ORM.ts

@@ -0,0 +1,398 @@
+/**
+ * ORM Class - Main Entry Point
+ *
+ * Database-agnostic ORM that works with any adapter implementing IDataAdapter.
+ *
+ * @example
+ * ```typescript
+ * import { ORM } from '@promakeai/orm';
+ * import { SqliteAdapter } from '@promakeai/dbcli';
+ *
+ * const adapter = new SqliteAdapter('./database.db');
+ * const db = new ORM(adapter);
+ *
+ * // List with filters and populate
+ * const posts = await db.list('posts', {
+ *   where: { published: true },
+ *   populate: ['userId', 'categoryIds'],
+ *   orderBy: [{ field: 'created_at', direction: 'DESC' }],
+ *   limit: 10,
+ * });
+ *
+ * // Create
+ * const post = await db.create('posts', { title: 'Hello', published: true });
+ *
+ * // Transaction
+ * await db.transaction(async (tx) => {
+ *   await tx.create('posts', { title: 'Post 1' });
+ *   await tx.create('posts', { title: 'Post 2' });
+ * });
+ * ```
+ */
+
+import type { IDataAdapter } from "./adapters/IDataAdapter";
+import type {
+  QueryOptions,
+  PaginatedResult,
+  SchemaDefinition,
+  ORMConfig,
+} from "./types";
+import { resolvePopulate, validatePopulate } from "./utils/populateResolver";
+
+/**
+ * Main ORM class - Completely adapter agnostic
+ */
+export class ORM {
+  private adapter: IDataAdapter;
+  private schema?: SchemaDefinition;
+  private defaultLang: string;
+  private fallbackLang?: string;
+
+  /**
+   * Create ORM instance with any adapter
+   *
+   * @param adapter - Any object implementing IDataAdapter interface
+   * @param config - Optional configuration
+   */
+  constructor(adapter: IDataAdapter, config?: ORMConfig) {
+    this.adapter = adapter;
+    this.schema = config?.schema;
+    this.defaultLang = config?.defaultLang || "en";
+    this.fallbackLang = config?.fallbackLang;
+  }
+
+  // ==================== Query Methods ====================
+
+  /**
+   * List records from table
+   *
+   * @example
+   * ```typescript
+   * // Simple list
+   * const products = await db.list('products');
+   *
+   * // With populate
+   * const products = await db.list('products', {
+   *   where: { active: true },
+   *   populate: ['categoryId', 'brandId'],
+   *   limit: 10,
+   * });
+   * // Each product has .category and .brand objects
+   *
+   * // Nested populate
+   * const orders = await db.list('orders', {
+   *   populate: [
+   *     'userId',
+   *     { path: 'items', populate: ['productId'] }
+   *   ]
+   * });
+   * ```
+   */
+  async list<T = unknown>(
+    table: string,
+    options?: QueryOptions
+  ): Promise<T[]> {
+    const opts = this.normalizeOptions(options);
+    const { populate, ...queryOpts } = opts;
+
+    // Fetch records
+    let records = await this.adapter.list<T>(table, queryOpts);
+
+    // Resolve populate if schema is available
+    if (populate && this.schema) {
+      records = await this.resolvePopulateForRecords(records, table, populate);
+    }
+
+    return records;
+  }
+
+  /**
+   * Get single record by ID
+   *
+   * @example
+   * ```typescript
+   * const product = await db.get('products', 1, {
+   *   populate: ['categoryId']
+   * });
+   * console.log(product.category.name);
+   * ```
+   */
+  async get<T = unknown>(
+    table: string,
+    id: string | number,
+    options?: QueryOptions
+  ): Promise<T | null> {
+    const opts = this.normalizeOptions(options);
+    const { populate, ...queryOpts } = opts;
+
+    const record = await this.adapter.get<T>(table, id, queryOpts);
+
+    // Resolve populate if record found and schema is available
+    if (record && populate && this.schema) {
+      const [populated] = await this.resolvePopulateForRecords(
+        [record],
+        table,
+        populate
+      );
+      return populated;
+    }
+
+    return record;
+  }
+
+  /**
+   * Count records
+   */
+  async count(table: string, options?: QueryOptions): Promise<number> {
+    const opts = this.normalizeOptions(options);
+    return this.adapter.count(table, opts);
+  }
+
+  /**
+   * Paginated query
+   */
+  async paginate<T = unknown>(
+    table: string,
+    page: number,
+    limit: number,
+    options?: QueryOptions
+  ): Promise<PaginatedResult<T>> {
+    const opts = this.normalizeOptions(options);
+    return this.adapter.paginate<T>(table, page, limit, opts);
+  }
+
+  // ==================== Write Methods ====================
+
+  /**
+   * Create new record
+   */
+  async create<T = unknown>(
+    table: string,
+    data: Record<string, unknown>
+  ): Promise<T> {
+    // Validate if schema exists
+    if (this.schema) {
+      this.validateData(table, data);
+    }
+    return this.adapter.create<T>(table, data);
+  }
+
+  /**
+   * Update record by ID
+   */
+  async update<T = unknown>(
+    table: string,
+    id: string | number,
+    data: Record<string, unknown>
+  ): Promise<T> {
+    // Validate if schema exists
+    if (this.schema) {
+      this.validateData(table, data, true);
+    }
+    return this.adapter.update<T>(table, id, data);
+  }
+
+  /**
+   * Delete record by ID
+   */
+  async delete(table: string, id: string | number): Promise<boolean> {
+    return this.adapter.delete(table, id);
+  }
+
+  // ==================== Batch Methods ====================
+
+  /**
+   * Create multiple records
+   */
+  async createMany<T = unknown>(
+    table: string,
+    records: Record<string, unknown>[],
+    options?: { ignore?: boolean }
+  ): Promise<{ created: number; ids: (number | bigint)[] }> {
+    return this.adapter.createMany<T>(table, records, options);
+  }
+
+  /**
+   * Update multiple records
+   */
+  async updateMany(
+    table: string,
+    updates: { id: number | string; data: Record<string, unknown> }[]
+  ): Promise<{ updated: number }> {
+    return this.adapter.updateMany(table, updates);
+  }
+
+  /**
+   * Delete multiple records
+   */
+  async deleteMany(
+    table: string,
+    ids: (number | string)[]
+  ): Promise<{ deleted: number }> {
+    return this.adapter.deleteMany(table, ids);
+  }
+
+  // ==================== Raw Query Methods ====================
+
+  /**
+   * Execute raw query
+   */
+  async raw<T = unknown>(query: string, params?: unknown[]): Promise<T[]> {
+    return this.adapter.raw<T>(query, params);
+  }
+
+  /**
+   * Execute raw statement
+   */
+  async execute(
+    query: string,
+    params?: unknown[]
+  ): Promise<{ changes: number; lastInsertRowid: number | bigint }> {
+    return this.adapter.execute(query, params);
+  }
+
+  // ==================== Transaction ====================
+
+  /**
+   * Transaction wrapper
+   *
+   * @example
+   * ```typescript
+   * await db.transaction(async (tx) => {
+   *   const user = await tx.create('users', { name: 'John' });
+   *   await tx.create('posts', { title: 'Hello', userId: user.id });
+   * });
+   * ```
+   */
+  async transaction<T>(callback: (orm: ORM) => Promise<T>): Promise<T> {
+    await this.adapter.beginTransaction();
+
+    try {
+      const result = await callback(this);
+      await this.adapter.commit();
+      return result;
+    } catch (error) {
+      await this.adapter.rollback();
+      throw error;
+    }
+  }
+
+  // ==================== Schema Methods ====================
+
+  /**
+   * Get all table names
+   */
+  async getTables(): Promise<string[]> {
+    if (this.adapter.getTables) {
+      return this.adapter.getTables();
+    }
+    throw new Error("Adapter does not support getTables()");
+  }
+
+  /**
+   * Get table schema
+   */
+  async getTableSchema(table: string): Promise<unknown[]> {
+    if (this.adapter.getTableSchema) {
+      return this.adapter.getTableSchema(table);
+    }
+    throw new Error("Adapter does not support getTableSchema()");
+  }
+
+  // ==================== Lifecycle ====================
+
+  /**
+   * Close connection
+   */
+  async close(): Promise<void> {
+    return this.adapter.close();
+  }
+
+  // ==================== Internal Methods ====================
+
+  /**
+   * Normalize query options
+   */
+  private normalizeOptions(options?: QueryOptions): QueryOptions {
+    return {
+      ...options,
+      lang: options?.lang || this.defaultLang,
+      fallbackLang: options?.fallbackLang || this.fallbackLang,
+    };
+  }
+
+  /**
+   * Validate data against schema
+   */
+  private validateData(
+    table: string,
+    data: Record<string, unknown>,
+    isUpdate = false
+  ): void {
+    if (!this.schema) return;
+
+    const tableDef = this.schema.tables[table];
+    if (!tableDef) {
+      throw new Error(`Table "${table}" not found in schema`);
+    }
+
+    // Skip validation for now - can be implemented with more detailed checks
+    // This is a placeholder for future validation logic
+  }
+
+  /**
+   * Resolve populate for records
+   */
+  private async resolvePopulateForRecords<T>(
+    records: T[],
+    table: string,
+    populate: QueryOptions["populate"]
+  ): Promise<T[]> {
+    if (!this.schema) return records;
+
+    // Validate populate options
+    const validation = validatePopulate(populate, table, this.schema);
+    if (!validation.valid) {
+      console.warn("Populate validation warnings:", validation.errors);
+    }
+
+    // Create adapter wrapper for populate resolver
+    const adapterWrapper = {
+      findMany: <R = unknown>(
+        t: string,
+        opts?: { where?: Record<string, unknown> }
+      ): Promise<R[]> => {
+        return this.adapter.list<R>(t, opts);
+      },
+    };
+
+    return resolvePopulate<T>(
+      records,
+      table,
+      populate,
+      this.schema,
+      adapterWrapper
+    );
+  }
+
+  /**
+   * Get the underlying adapter (for advanced usage)
+   */
+  getAdapter(): IDataAdapter {
+    return this.adapter;
+  }
+
+  /**
+   * Get current schema (if set)
+   */
+  getSchema(): SchemaDefinition | undefined {
+    return this.schema;
+  }
+
+  /**
+   * Set schema
+   */
+  setSchema(schema: SchemaDefinition): void {
+    this.schema = schema;
+  }
+}

package/src/adapters/IDataAdapter.ts

@@ -0,0 +1,196 @@
+/**
+ * Data Adapter Interface
+ *
+ * All data sources must implement this interface.
+ * This is the contract between ORM and adapters.
+ *
+ * Features:
+ * - Built-in multi-language support via lang option
+ * - Automatic translation handling for translatable fields
+ * - MongoDB-style populate for references
+ */
+
+import type { QueryOptions, PaginatedResult, SchemaDefinition } from "../types";
+
+/**
+ * Generic Data Adapter Interface
+ */
+export interface IDataAdapter {
+  /**
+   * Schema definition for translation support (optional)
+   */
+  schema?: SchemaDefinition;
+
+  /**
+   * Default language for translations
+   */
+  defaultLang?: string;
+
+  /**
+   * Set schema after construction
+   */
+  setSchema?(schema: SchemaDefinition): void;
+
+  /**
+   * Initialize the adapter (optional)
+   */
+  connect?(): void | Promise<void>;
+
+  // ==================== Query Methods ====================
+
+  /**
+   * List records from table
+   */
+  list<T = unknown>(table: string, options?: QueryOptions): Promise<T[]>;
+
+  /**
+   * Get single record by ID
+   */
+  get<T = unknown>(
+    table: string,
+    id: string | number,
+    options?: QueryOptions
+  ): Promise<T | null>;
+
+  /**
+   * Count records matching condition
+   */
+  count(table: string, options?: QueryOptions): Promise<number>;
+
+  /**
+   * Query with pagination
+   */
+  paginate<T = unknown>(
+    table: string,
+    page: number,
+    limit: number,
+    options?: QueryOptions
+  ): Promise<PaginatedResult<T>>;
+
+  // ==================== Write Methods ====================
+
+  /**
+   * Create new record
+   */
+  create<T = unknown>(table: string, data: Record<string, unknown>): Promise<T>;
+
+  /**
+   * Update record by ID
+   */
+  update<T = unknown>(
+    table: string,
+    id: string | number,
+    data: Record<string, unknown>
+  ): Promise<T>;
+
+  /**
+   * Delete record by ID
+   */
+  delete(table: string, id: string | number): Promise<boolean>;
+
+  // ==================== Batch Methods ====================
+
+  /**
+   * Create multiple records
+   */
+  createMany<T = unknown>(
+    table: string,
+    records: Record<string, unknown>[],
+    options?: { ignore?: boolean }
+  ): Promise<{ created: number; ids: (number | bigint)[] }>;
+
+  /**
+   * Update multiple records
+   */
+  updateMany(
+    table: string,
+    updates: { id: number | string; data: Record<string, unknown> }[]
+  ): Promise<{ updated: number }>;
+
+  /**
+   * Delete multiple records
+   */
+  deleteMany(
+    table: string,
+    ids: (number | string)[]
+  ): Promise<{ deleted: number }>;
+
+  // ==================== Translation Methods ====================
+
+  /**
+   * Create record with translations in a single transaction
+   * If translations not provided but data contains translatable fields,
+   * those fields are automatically added as defaultLang translation
+   */
+  createWithTranslations<T = unknown>(
+    table: string,
+    data: Record<string, unknown>,
+    translations?: Record<string, Record<string, unknown>>
+  ): Promise<T>;
+
+  /**
+   * Update or insert translation for specific language
+   */
+  upsertTranslation(
+    table: string,
+    id: string | number,
+    lang: string,
+    data: Record<string, unknown>
+  ): Promise<void>;
+
+  /**
+   * Get all translations for a record
+   */
+  getTranslations<T = unknown>(table: string, id: string | number): Promise<T[]>;
+
+  // ==================== Raw Query Methods ====================
+
+  /**
+   * Execute raw query (adapter-specific)
+   */
+  raw<T = unknown>(query: string, params?: unknown[]): Promise<T[]>;
+
+  /**
+   * Execute raw statement (for INSERT/UPDATE/DELETE)
+   */
+  execute(
+    query: string,
+    params?: unknown[]
+  ): Promise<{ changes: number; lastInsertRowid: number | bigint }>;
+
+  // ==================== Transaction Methods ====================
+
+  /**
+   * Begin transaction
+   */
+  beginTransaction(): Promise<void>;
+
+  /**
+   * Commit transaction
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rollback transaction
+   */
+  rollback(): Promise<void>;
+
+  // ==================== Schema Methods ====================
+
+  /**
+   * Get all table names
+   */
+  getTables?(): Promise<string[]>;
+
+  /**
+   * Get table schema/structure
+   */
+  getTableSchema?(table: string): Promise<unknown[]>;
+
+  // ==================== Lifecycle ====================
+
+  /**
+   * Close connection
+   */
+  close(): void | Promise<void>;
+}