@promakeai/orm 1.0.0

package/src/index.ts

@@ -0,0 +1,148 @@
+/**
+ * @promakeai/orm - Database-Agnostic ORM
+ *
+ * Works in browser and Node.js with any adapter implementing IDataAdapter.
+ *
+ * @example
+ * ```typescript
+ * import { ORM, defineSchema, f } from '@promakeai/orm';
+ *
+ * // Define schema
+ * const schema = defineSchema({
+ *   languages: ['en', 'tr'],
+ *   tables: {
+ *     products: {
+ *       id: f.id(),
+ *       name: f.string().translatable().required(),
+ *       price: f.decimal().required(),
+ *       categoryId: f.int().ref('categories'),
+ *     },
+ *     categories: {
+ *       id: f.id(),
+ *       name: f.string().translatable().required(),
+ *     },
+ *   },
+ * });
+ *
+ * // Use with adapter
+ * const db = new ORM(adapter, { schema });
+ * const products = await db.list('products', {
+ *   where: { price: { $gt: 100 } },
+ *   populate: ['categoryId'],
+ * });
+ * ```
+ */
+
+// Main ORM Class
+export { ORM } from "./ORM";
+
+// Adapter Interface
+export type { IDataAdapter } from "./adapters/IDataAdapter";
+
+// Schema API
+export {
+  defineSchema,
+  f,
+  mergeSchemas,
+  createSchemaUnsafe,
+} from "./schema";
+export type { FieldBuilder } from "./schema";
+
+// Schema Validation
+export {
+  validateSchema,
+  assertValidSchema,
+  isValidSchema,
+  validateTable,
+  ValidationErrorCode,
+} from "./schema";
+export type { ValidationError } from "./schema";
+
+// String Helpers
+export {
+  singularize,
+  pluralize,
+  toPascalCase,
+  toCamelCase,
+  toSnakeCase,
+  toInterfaceName,
+  toDbInterfaceName,
+  toPascalCasePlural,
+  toTranslationTableName,
+  toTranslationFKName,
+} from "./schema";
+
+// Schema Helpers
+export {
+  getTranslatableFields,
+  getNonTranslatableFields,
+  getInsertableFields,
+  hasTranslatableFields,
+  getPrimaryKeyField,
+  getReferenceFields,
+  getMainTableFields,
+  getTranslationTableFields,
+  isRequiredField,
+  getRequiredFields,
+  getRefTarget,
+  getRefTargetFull,
+} from "./schema";
+
+// Query Builder
+export { buildWhereClause } from "./utils/whereBuilder";
+export type { WhereResult } from "./utils/whereBuilder";
+
+// Translation Query Builder
+export {
+  buildTranslationQuery,
+  buildTranslationQueryById,
+  buildTranslationInsert,
+  buildTranslationUpsert,
+  extractTranslatableData,
+} from "./utils/translationQuery";
+export type {
+  TranslationQueryOptions,
+  TranslationQueryResult,
+} from "./utils/translationQuery";
+
+// Populate Resolver
+export {
+  resolvePopulate,
+  getPopulatableFields,
+  validatePopulate,
+} from "./utils/populateResolver";
+export type { PopulateAdapter } from "./utils/populateResolver";
+
+// JSON Schema Converter
+export { parseJSONSchema } from "./utils/jsonConverter";
+
+// Types
+export type {
+  // Field types
+  FieldType,
+  FieldDefinition,
+  FieldReference,
+  FieldBuilderLike,
+
+  // Schema types
+  TableDefinition,
+  LanguageConfig,
+  SchemaDefinition,
+  SchemaInput,
+
+  // JSON Schema types (AI-friendly)
+  JSONFieldDefinition,
+  JSONTableDefinition,
+  JSONSchemaDefinition,
+
+  // Query types
+  WhereCondition,
+  OrderByOption,
+  PopulateOption,
+  PopulateNested,
+  QueryOptions,
+  PaginatedResult,
+
+  // Config
+  ORMConfig,
+} from "./types";

package/src/schema/defineSchema.ts

@@ -0,0 +1,164 @@
+/**
+ * Schema Definition API
+ *
+ * Main entry point for defining database schemas.
+ *
+ * @example
+ * ```typescript
+ * import { defineSchema, f } from '@promakeai/orm';
+ *
+ * export default defineSchema({
+ *   languages: ['en', 'tr', 'de'],
+ *   tables: {
+ *     products: {
+ *       id: f.id(),
+ *       price: f.decimal().required(),
+ *       name: f.string().translatable().required(),
+ *       category_id: f.int().ref('categories'),
+ *     },
+ *     categories: {
+ *       id: f.id(),
+ *       slug: f.string().required().unique(),
+ *       name: f.string().translatable().required(),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+import type {
+  SchemaDefinition,
+  SchemaInput,
+  TableDefinition,
+  LanguageConfig,
+  FieldBuilderLike,
+} from "../types";
+import { assertValidSchema } from "./validator";
+
+// Re-export f for convenience
+export { f } from "./fieldBuilder";
+
+/**
+ * Define a database schema with type-safe DSL
+ *
+ * @param input - Schema definition with languages and tables
+ * @returns Validated SchemaDefinition
+ * @throws Error if schema is invalid
+ */
+export function defineSchema(input: SchemaInput): SchemaDefinition {
+  // 1. Normalize languages
+  const languages = normalizeLanguages(input.languages);
+
+  // 2. Build each table's fields from DSL
+  const tables: Record<string, TableDefinition> = {};
+
+  for (const [tableName, fields] of Object.entries(input.tables)) {
+    tables[tableName] = {
+      name: tableName,
+      fields: Object.fromEntries(
+        Object.entries(fields).map(([fieldName, builder]) => [
+          fieldName,
+          (builder as FieldBuilderLike).build(),
+        ])
+      ),
+    };
+  }
+
+  // 3. Create schema definition
+  const schema: SchemaDefinition = {
+    name: input.name,
+    languages,
+    tables,
+  };
+
+  // 4. Validate
+  assertValidSchema(schema);
+
+  return schema;
+}
+
+/**
+ * Normalize language input to LanguageConfig
+ */
+function normalizeLanguages(input: string[] | LanguageConfig): LanguageConfig {
+  if (Array.isArray(input)) {
+    if (input.length === 0) {
+      throw new Error("At least one language must be defined");
+    }
+    return {
+      default: input[0],
+      supported: input,
+    };
+  }
+  return input;
+}
+
+/**
+ * Create schema without validation (for testing/internal use)
+ * @internal
+ */
+export function createSchemaUnsafe(input: SchemaInput): SchemaDefinition {
+  const languages = normalizeLanguages(input.languages);
+
+  const tables: Record<string, TableDefinition> = {};
+  for (const [tableName, fields] of Object.entries(input.tables)) {
+    tables[tableName] = {
+      name: tableName,
+      fields: Object.fromEntries(
+        Object.entries(fields).map(([fieldName, builder]) => [
+          fieldName,
+          (builder as FieldBuilderLike).build(),
+        ])
+      ),
+    };
+  }
+
+  return {
+    name: input.name,
+    languages,
+    tables,
+  };
+}
+
+/**
+ * Merge multiple schemas into one
+ *
+ * @param schemas - Array of schema definitions to merge
+ * @returns Merged schema definition
+ * @throws Error if table names conflict
+ */
+export function mergeSchemas(schemas: SchemaDefinition[]): SchemaDefinition {
+  if (schemas.length === 0) {
+    throw new Error("At least one schema is required");
+  }
+
+  // Use first schema's default language
+  const defaultLang = schemas[0].languages.default;
+
+  // Collect all languages (unique)
+  const allLangs = new Set<string>();
+  for (const schema of schemas) {
+    for (const lang of schema.languages.supported) {
+      allLangs.add(lang);
+    }
+  }
+
+  // Merge tables
+  const tables: Record<string, TableDefinition> = {};
+  for (const schema of schemas) {
+    for (const [tableName, table] of Object.entries(schema.tables)) {
+      if (tables[tableName]) {
+        throw new Error(`Duplicate table name across schemas: ${tableName}`);
+      }
+      tables[tableName] = table;
+    }
+  }
+
+  return {
+    languages: {
+      default: defaultLang,
+      supported: Array.from(allLangs),
+    },
+    tables,
+  };
+}

package/src/schema/fieldBuilder.ts

@@ -0,0 +1,244 @@
+/**
+ * Field Builder DSL
+ *
+ * Type-safe fluent API for field definitions.
+ *
+ * @example
+ * ```typescript
+ * import { f } from '@promakeai/orm';
+ *
+ * const schema = defineSchema({
+ *   tables: {
+ *     products: {
+ *       id: f.id(),
+ *       price: f.decimal().required().min(0),
+ *       name: f.string().translatable().required().trim(),
+ *       email: f.string().lowercase().trim().unique(),
+ *       categoryId: f.int().ref('categories'),
+ *       brandId: f.int().ref({ table: 'brands', onDelete: 'SET_NULL' }),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+import type { FieldDefinition, FieldType, FieldReference } from "../types";
+
+/**
+ * Fluent builder for field definitions
+ */
+export class FieldBuilder {
+  protected definition: FieldDefinition;
+
+  constructor(type: FieldType) {
+    this.definition = {
+      type,
+      nullable: true, // Default nullable
+      unique: false,
+      primary: false,
+      translatable: false,
+    };
+  }
+
+  /**
+   * Mark field as NOT NULL
+   */
+  required(): this {
+    this.definition.nullable = false;
+    return this;
+  }
+
+  /**
+   * Mark field as nullable (default)
+   */
+  nullable(): this {
+    this.definition.nullable = true;
+    return this;
+  }
+
+  /**
+   * Mark field as UNIQUE
+   */
+  unique(): this {
+    this.definition.unique = true;
+    return this;
+  }
+
+  /**
+   * Set default value
+   */
+  default(value: unknown): this {
+    this.definition.default = value;
+    return this;
+  }
+
+  /**
+   * Mark field as translatable (stored in translation table)
+   * Only valid for string/text fields
+   */
+  translatable(): this {
+    this.definition.translatable = true;
+    return this;
+  }
+
+  /**
+   * Add reference to another table (MongoDB-style)
+   * @param tableOrOptions - Table name or options object
+   */
+  ref(
+    tableOrOptions:
+      | string
+      | {
+          table: string;
+          field?: string;
+          onDelete?: "CASCADE" | "SET_NULL" | "RESTRICT" | "NO_ACTION";
+          onUpdate?: "CASCADE" | "SET_NULL" | "RESTRICT" | "NO_ACTION";
+        }
+  ): this {
+    this.definition.ref = tableOrOptions;
+    return this;
+  }
+
+  /**
+   * Trim whitespace from string values
+   */
+  trim(): this {
+    this.definition.trim = true;
+    return this;
+  }
+
+  /**
+   * Convert string to lowercase
+   */
+  lowercase(): this {
+    this.definition.lowercase = true;
+    return this;
+  }
+
+  /**
+   * Convert string to uppercase
+   */
+  uppercase(): this {
+    this.definition.uppercase = true;
+    return this;
+  }
+
+  /**
+   * Minimum string length
+   */
+  minLength(value: number): this {
+    this.definition.minLength = value;
+    return this;
+  }
+
+  /**
+   * Maximum string length
+   */
+  maxLength(value: number): this {
+    this.definition.maxLength = value;
+    return this;
+  }
+
+  /**
+   * Minimum numeric value
+   */
+  min(value: number): this {
+    this.definition.min = value;
+    return this;
+  }
+
+  /**
+   * Maximum numeric value
+   */
+  max(value: number): this {
+    this.definition.max = value;
+    return this;
+  }
+
+  /**
+   * Enum values (allowed values)
+   */
+  enum(values: string[]): this {
+    this.definition.enum = values;
+    return this;
+  }
+
+  /**
+   * RegExp pattern to match
+   */
+  match(pattern: string): this {
+    this.definition.match = pattern;
+    return this;
+  }
+
+  /**
+   * Build the final field definition
+   * @internal
+   */
+  build(): FieldDefinition {
+    return { ...this.definition };
+  }
+}
+
+/**
+ * Factory object for creating field builders
+ *
+ * @example
+ * ```typescript
+ * f.id()                              // Primary key
+ * f.string().required().trim()        // NOT NULL trimmed string
+ * f.int().default(0).min(0)           // Non-negative integer
+ * f.string().unique().lowercase()     // Unique lowercase string
+ * f.string().translatable().required() // Translatable NOT NULL
+ * f.int().ref('users')                // Foreign key to users
+ * f.int().ref({ table: 'users', onDelete: 'CASCADE' }) // With constraint
+ * f.json().ref('categories')          // Array of category IDs
+ * ```
+ */
+export const f = {
+  /**
+   * Primary key field (INTEGER PRIMARY KEY AUTOINCREMENT)
+   */
+  id: (): FieldBuilder => {
+    const builder = new FieldBuilder("id");
+    builder["definition"].primary = true;
+    builder["definition"].nullable = false;
+    return builder;
+  },
+
+  /**
+   * String field (VARCHAR/TEXT)
+   */
+  string: (): FieldBuilder => new FieldBuilder("string"),
+
+  /**
+   * Text field (TEXT/LONGTEXT)
+   */
+  text: (): FieldBuilder => new FieldBuilder("text"),
+
+  /**
+   * Integer field (INTEGER)
+   */
+  int: (): FieldBuilder => new FieldBuilder("int"),
+
+  /**
+   * Decimal field (REAL/DECIMAL)
+   */
+  decimal: (): FieldBuilder => new FieldBuilder("decimal"),
+
+  /**
+   * Boolean field (INTEGER 0/1 in SQLite)
+   */
+  bool: (): FieldBuilder => new FieldBuilder("bool"),
+
+  /**
+   * Timestamp field (TEXT in ISO format)
+   */
+  timestamp: (): FieldBuilder => new FieldBuilder("timestamp"),
+
+  /**
+   * JSON field (TEXT with JSON serialization)
+   */
+  json: (): FieldBuilder => new FieldBuilder("json"),
+};
+

package/src/schema/helpers.ts

@@ -0,0 +1,171 @@
+/**
+ * String Helper Functions
+ *
+ * Utilities for transforming table/field names.
+ */
+
+/**
+ * Convert plural word to singular
+ *
+ * @example
+ * ```typescript
+ * singularize('products')    // 'product'
+ * singularize('categories')  // 'category'
+ * singularize('users')       // 'user'
+ * ```
+ */
+export function singularize(word: string): string {
+  const irregulars: Record<string, string> = {
+    people: "person",
+    children: "child",
+    men: "man",
+    women: "woman",
+    teeth: "tooth",
+    feet: "foot",
+    mice: "mouse",
+    geese: "goose",
+  };
+
+  if (irregulars[word]) {
+    return irregulars[word];
+  }
+
+  // -ies → -y (categories → category)
+  if (word.endsWith("ies")) {
+    return word.slice(0, -3) + "y";
+  }
+
+  // -ses, -xes, -zes, -ches, -shes → remove 'es'
+  if (
+    word.endsWith("ses") ||
+    word.endsWith("xes") ||
+    word.endsWith("zes") ||
+    word.endsWith("ches") ||
+    word.endsWith("shes")
+  ) {
+    return word.slice(0, -2);
+  }
+
+  // -es → remove 'es' for words ending in -o
+  if (word.endsWith("oes")) {
+    return word.slice(0, -2);
+  }
+
+  // -s → remove 's'
+  if (word.endsWith("s") && !word.endsWith("ss")) {
+    return word.slice(0, -1);
+  }
+
+  return word;
+}
+
+/**
+ * Convert string to PascalCase
+ */
+export function toPascalCase(str: string): string {
+  return str
+    .split(/[_\-\s]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join("");
+}
+
+/**
+ * Convert string to camelCase
+ */
+export function toCamelCase(str: string): string {
+  const pascal = toPascalCase(str);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+/**
+ * Convert string to snake_case
+ */
+export function toSnakeCase(str: string): string {
+  return str
+    .replace(/([A-Z])/g, "_$1")
+    .replace(/[-\s]+/g, "_")
+    .toLowerCase()
+    .replace(/^_/, "");
+}
+
+/**
+ * Get singular PascalCase name for interface
+ */
+export function toInterfaceName(tableName: string): string {
+  return toPascalCase(singularize(tableName));
+}
+
+/**
+ * Get Db-prefixed interface name
+ * @example toDbInterfaceName('products') // 'DbProduct'
+ */
+export function toDbInterfaceName(tableName: string): string {
+  return "Db" + toInterfaceName(tableName);
+}
+
+/**
+ * Pluralize a word (basic implementation)
+ */
+export function pluralize(word: string): string {
+  const irregulars: Record<string, string> = {
+    person: "people",
+    child: "children",
+    man: "men",
+    woman: "women",
+    tooth: "teeth",
+    foot: "feet",
+    mouse: "mice",
+    goose: "geese",
+  };
+
+  if (irregulars[word]) {
+    return irregulars[word];
+  }
+
+  // -y → -ies (category → categories)
+  if (word.endsWith("y") && !/[aeiou]y$/.test(word)) {
+    return word.slice(0, -1) + "ies";
+  }
+
+  // -s, -x, -z, -ch, -sh → add 'es'
+  if (
+    word.endsWith("s") ||
+    word.endsWith("x") ||
+    word.endsWith("z") ||
+    word.endsWith("ch") ||
+    word.endsWith("sh")
+  ) {
+    return word + "es";
+  }
+
+  // -o → add 'es' for common words
+  if (word.endsWith("o") && /[^aeiou]o$/.test(word)) {
+    return word + "es";
+  }
+
+  // Default: add 's'
+  return word + "s";
+}
+
+/**
+ * Get PascalCase plural form
+ * @example toPascalCasePlural('products') // 'Products'
+ */
+export function toPascalCasePlural(tableName: string): string {
+  // Table names are usually already plural, just convert to PascalCase
+  return toPascalCase(tableName);
+}
+
+/**
+ * Get translation table name
+ */
+export function toTranslationTableName(tableName: string): string {
+  return `${tableName}_translations`;
+}
+
+/**
+ * Get foreign key column name for translation table
+ */
+export function toTranslationFKName(tableName: string): string {
+  return `${singularize(tableName)}_id`;
+}