@promakeai/orm 1.0.0

package/src/schema/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Schema Module Exports
+ */
+
+// Main API
+export { defineSchema, f, mergeSchemas, createSchemaUnsafe } from "./defineSchema";
+export type { FieldBuilder } from "./fieldBuilder";
+
+// Validation
+export {
+  validateSchema,
+  assertValidSchema,
+  isValidSchema,
+  validateTable,
+  ValidationErrorCode,
+} from "./validator";
+export type { ValidationError } from "./validator";
+
+// String Helpers
+export {
+  singularize,
+  pluralize,
+  toPascalCase,
+  toCamelCase,
+  toSnakeCase,
+  toInterfaceName,
+  toDbInterfaceName,
+  toPascalCasePlural,
+  toTranslationTableName,
+  toTranslationFKName,
+} from "./helpers";
+
+// Schema Helpers
+export {
+  getTranslatableFields,
+  getNonTranslatableFields,
+  getInsertableFields,
+  hasTranslatableFields,
+  getPrimaryKeyField,
+  getReferenceFields,
+  getMainTableFields,
+  getTranslationTableFields,
+  isRequiredField,
+  getRequiredFields,
+  getRefTarget,
+  getRefTargetFull,
+} from "./schemaHelpers";

package/src/schema/schemaHelpers.ts

@@ -0,0 +1,123 @@
+/**
+ * Schema Helper Functions
+ *
+ * Utilities for working with schema definitions.
+ */
+
+import type { TableDefinition, FieldDefinition, FieldReference } from "../types";
+
+/**
+ * Get names of translatable fields in a table
+ */
+export function getTranslatableFields(table: TableDefinition): string[] {
+  return Object.entries(table.fields)
+    .filter(([_, field]) => field.translatable)
+    .map(([name]) => name);
+}
+
+/**
+ * Get names of non-translatable fields in a table (excluding primary key)
+ */
+export function getNonTranslatableFields(table: TableDefinition): string[] {
+  return Object.entries(table.fields)
+    .filter(([_, field]) => !field.translatable && !field.primary)
+    .map(([name]) => name);
+}
+
+/**
+ * Get all non-primary key fields (for INSERT statements)
+ */
+export function getInsertableFields(table: TableDefinition): string[] {
+  return Object.entries(table.fields)
+    .filter(([_, field]) => !field.primary)
+    .map(([name]) => name);
+}
+
+/**
+ * Check if table has any translatable fields
+ */
+export function hasTranslatableFields(table: TableDefinition): boolean {
+  return getTranslatableFields(table).length > 0;
+}
+
+/**
+ * Get the primary key field name
+ */
+export function getPrimaryKeyField(table: TableDefinition): string | null {
+  const entry = Object.entries(table.fields).find(([_, field]) => field.primary);
+  return entry ? entry[0] : null;
+}
+
+/**
+ * Get fields with foreign key references (using ref)
+ */
+export function getReferenceFields(
+  table: TableDefinition
+): [string, FieldReference][] {
+  return Object.entries(table.fields)
+    .filter(([_, field]) => field.ref)
+    .map(([name, field]) => {
+      const ref = field.ref!;
+      // Normalize string to FieldReference
+      if (typeof ref === "string") {
+        return [name, { table: ref, field: "id" }];
+      }
+      return [name, { ...ref, field: ref.field || "id" }];
+    });
+}
+
+/**
+ * Get fields for main table (excluding translatable)
+ */
+export function getMainTableFields(
+  table: TableDefinition
+): [string, FieldDefinition][] {
+  return Object.entries(table.fields).filter(([_, field]) => !field.translatable);
+}
+
+/**
+ * Get fields for translation table
+ */
+export function getTranslationTableFields(
+  table: TableDefinition
+): [string, FieldDefinition][] {
+  return Object.entries(table.fields).filter(([_, field]) => field.translatable);
+}
+
+/**
+ * Check if a field is required (NOT NULL without default)
+ */
+export function isRequiredField(field: FieldDefinition): boolean {
+  return !field.nullable && field.default === undefined && !field.primary;
+}
+
+/**
+ * Get required fields for input validation
+ */
+export function getRequiredFields(table: TableDefinition): string[] {
+  return Object.entries(table.fields)
+    .filter(([_, field]) => isRequiredField(field))
+    .map(([name]) => name);
+}
+
+/**
+ * Get reference target table name from field
+ */
+export function getRefTarget(field: FieldDefinition): string | null {
+  if (!field.ref) return null;
+  return typeof field.ref === "string" ? field.ref : field.ref.table;
+}
+
+/**
+ * Get full reference target (table and field) from field
+ * Returns { table, field } object
+ */
+export function getRefTargetFull(
+  field: FieldDefinition
+): FieldReference | null {
+  if (!field.ref) return null;
+  if (typeof field.ref === "string") {
+    return { table: field.ref, field: "id" };
+  }
+  return { table: field.ref.table, field: field.ref.field || "id" };
+}

package/src/schema/validator.ts

@@ -0,0 +1,189 @@
+/**
+ * Schema Validator
+ *
+ * Validates schema definitions for correctness.
+ */
+
+import type { SchemaDefinition, TableDefinition } from "../types";
+import { getRefTarget } from "./schemaHelpers";
+
+/**
+ * Validation error with context
+ */
+export interface ValidationError {
+  table: string;
+  field?: string;
+  message: string;
+  code: string;
+}
+
+/**
+ * Error codes for validation
+ */
+export const ValidationErrorCode = {
+  MISSING_PRIMARY_KEY: "MISSING_PRIMARY_KEY",
+  INVALID_REFERENCE: "INVALID_REFERENCE",
+  INVALID_TRANSLATABLE_TYPE: "INVALID_TRANSLATABLE_TYPE",
+  NO_LANGUAGES: "NO_LANGUAGES",
+  DUPLICATE_TABLE: "DUPLICATE_TABLE",
+  RESERVED_FIELD_NAME: "RESERVED_FIELD_NAME",
+  SELF_REFERENCE_ON_REQUIRED: "SELF_REFERENCE_ON_REQUIRED",
+} as const;
+
+/**
+ * Reserved field names that cannot be used
+ */
+const RESERVED_FIELDS = ["language_code"];
+
+/**
+ * Validate a schema definition
+ *
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateSchema(schema: SchemaDefinition): ValidationError[] {
+  const errors: ValidationError[] = [];
+  const tableNames = Object.keys(schema.tables);
+
+  // Check languages
+  if (!schema.languages.supported || schema.languages.supported.length === 0) {
+    errors.push({
+      table: "_schema",
+      message: "At least one language must be defined",
+      code: ValidationErrorCode.NO_LANGUAGES,
+    });
+  }
+
+  // Validate each table
+  for (const [tableName, table] of Object.entries(schema.tables)) {
+    // Check for primary key
+    const hasPrimaryKey = Object.values(table.fields).some(
+      (field) => field.primary
+    );
+    if (!hasPrimaryKey) {
+      errors.push({
+        table: tableName,
+        message: "Table must have a primary key (use f.id())",
+        code: ValidationErrorCode.MISSING_PRIMARY_KEY,
+      });
+    }
+
+    // Validate each field
+    for (const [fieldName, field] of Object.entries(table.fields)) {
+      // Check reserved field names
+      if (RESERVED_FIELDS.includes(fieldName)) {
+        errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `'${fieldName}' is a reserved field name`,
+          code: ValidationErrorCode.RESERVED_FIELD_NAME,
+        });
+      }
+
+      // Check foreign key references (using ref)
+      const refTarget = getRefTarget(field);
+      if (refTarget) {
+        // Check if referenced table exists
+        if (!tableNames.includes(refTarget)) {
+          errors.push({
+            table: tableName,
+            field: fieldName,
+            message: `Foreign key references non-existent table: ${refTarget}`,
+            code: ValidationErrorCode.INVALID_REFERENCE,
+          });
+        }
+
+        // Check for required self-reference
+        if (refTarget === tableName && !field.nullable) {
+          errors.push({
+            table: tableName,
+            field: fieldName,
+            message: `Self-referencing foreign key must be nullable`,
+            code: ValidationErrorCode.SELF_REFERENCE_ON_REQUIRED,
+          });
+        }
+      }
+
+      // Check translatable field type
+      if (field.translatable && !["string", "text"].includes(field.type)) {
+        errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `Only string/text fields can be translatable, got: ${field.type}`,
+          code: ValidationErrorCode.INVALID_TRANSLATABLE_TYPE,
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate schema and throw if invalid
+ */
+export function assertValidSchema(schema: SchemaDefinition): void {
+  const errors = validateSchema(schema);
+
+  if (errors.length > 0) {
+    const messages = errors.map((e) =>
+      e.field
+        ? `[${e.table}.${e.field}] ${e.message}`
+        : `[${e.table}] ${e.message}`
+    );
+    throw new Error(`Schema validation failed:\n${messages.join("\n")}`);
+  }
+}
+
+/**
+ * Check if schema is valid (returns boolean)
+ */
+export function isValidSchema(schema: SchemaDefinition): boolean {
+  return validateSchema(schema).length === 0;
+}
+
+/**
+ * Validate a single table definition
+ */
+export function validateTable(
+  tableName: string,
+  table: TableDefinition,
+  allTableNames: string[]
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Check for primary key
+  const hasPrimaryKey = Object.values(table.fields).some(
+    (field) => field.primary
+  );
+  if (!hasPrimaryKey) {
+    errors.push({
+      table: tableName,
+      message: "Table must have a primary key",
+      code: ValidationErrorCode.MISSING_PRIMARY_KEY,
+    });
+  }
+
+  // Validate fields
+  for (const [fieldName, field] of Object.entries(table.fields)) {
+    const refTarget = getRefTarget(field);
+    if (refTarget && !allTableNames.includes(refTarget)) {
+      errors.push({
+        table: tableName,
+        field: fieldName,
+        message: `Foreign key references non-existent table: ${refTarget}`,
+        code: ValidationErrorCode.INVALID_REFERENCE,
+      });
+    }
+
+    if (field.translatable && !["string", "text"].includes(field.type)) {
+      errors.push({
+        table: tableName,
+        field: fieldName,
+        message: `Only string/text fields can be translatable`,
+        code: ValidationErrorCode.INVALID_TRANSLATABLE_TYPE,
+      });
+    }
+  }
+
+  return errors;
+}

package/src/types.ts

@@ -0,0 +1,243 @@
+/**
+ * @promakeai/orm Core Type Definitions
+ *
+ * Database-agnostic types that work in browser and Node.js
+ */
+
+// ==================== Field Types ====================
+
+/**
+ * Supported field types
+ */
+export type FieldType =
+  | "id"
+  | "string"
+  | "text"
+  | "int"
+  | "decimal"
+  | "bool"
+  | "timestamp"
+  | "json";
+
+/**
+ * Foreign key reference definition (MongoDB-style)
+ */
+export interface FieldReference {
+  table: string;
+  field?: string; // Default: 'id'
+  onDelete?: "CASCADE" | "SET_NULL" | "RESTRICT" | "NO_ACTION";
+  onUpdate?: "CASCADE" | "SET_NULL" | "RESTRICT" | "NO_ACTION";
+}
+
+/**
+ * Complete field definition after DSL processing
+ */
+export interface FieldDefinition {
+  type: FieldType;
+  nullable: boolean;
+  unique: boolean;
+  primary: boolean;
+  default?: unknown;
+  translatable: boolean;
+
+  // Reference (MongoDB-style)
+  ref?: string | FieldReference;
+
+  // Mongoose-style validations & transformations
+  required?: boolean;
+  trim?: boolean;
+  lowercase?: boolean;
+  uppercase?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  enum?: string[];
+  match?: string; // RegExp pattern as string
+}
+
+// ==================== Table & Schema Types ====================
+
+/**
+ * Table definition with all fields
+ */
+export interface TableDefinition {
+  name: string;
+  fields: Record<string, FieldDefinition>;
+}
+
+/**
+ * Language configuration
+ */
+export interface LanguageConfig {
+  default: string;
+  supported: string[];
+}
+
+/**
+ * Complete schema definition
+ */
+export interface SchemaDefinition {
+  name?: string;
+  languages: LanguageConfig;
+  tables: Record<string, TableDefinition>;
+}
+
+/**
+ * Interface for FieldBuilder-like objects (for type checking)
+ */
+export interface FieldBuilderLike {
+  build(): FieldDefinition;
+}
+
+/**
+ * Raw schema input before processing (from user DSL)
+ */
+export interface SchemaInput {
+  name?: string;
+  languages: string[] | LanguageConfig;
+  tables: Record<string, Record<string, FieldBuilderLike>>;
+}
+
+// ==================== JSON Schema Types (AI Agent Friendly) ====================
+
+/**
+ * JSON Schema Field Definition
+ */
+export interface JSONFieldDefinition {
+  type: FieldType;
+  translatable?: boolean;
+  required?: boolean;
+  unique?: boolean;
+  primary?: boolean;
+  nullable?: boolean;
+  default?: unknown;
+
+  // Numeric fields
+  precision?: number;
+  scale?: number;
+  min?: number;
+  max?: number;
+
+  // String fields
+  trim?: boolean;
+  lowercase?: boolean;
+  uppercase?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  enum?: string[];
+  match?: string;
+
+  // Reference (MongoDB-style)
+  ref?:
+    | string
+    | {
+        table: string;
+        field?: string;
+        onDelete?: "CASCADE" | "SET_NULL" | "RESTRICT" | "NO_ACTION";
+        onUpdate?: "CASCADE" | "SET_NULL" | "RESTRICT" | "NO_ACTION";
+      };
+}
+
+/**
+ * JSON Schema Table Definition
+ */
+export interface JSONTableDefinition {
+  [fieldName: string]: JSONFieldDefinition;
+}
+
+/**
+ * Complete JSON Schema Definition
+ */
+export interface JSONSchemaDefinition {
+  name?: string;
+  languages: string[];
+  defaultLanguage?: string;
+  tables: {
+    [tableName: string]: JSONTableDefinition;
+  };
+}
+
+// ==================== Query Types ====================
+
+/**
+ * MongoDB-style WHERE operators
+ */
+export interface WhereCondition {
+  $eq?: unknown;
+  $ne?: unknown;
+  $gt?: number;
+  $gte?: number;
+  $lt?: number;
+  $lte?: number;
+  $in?: unknown[];
+  $nin?: unknown[];
+  $like?: string;
+  $notLike?: string;
+  $between?: [unknown, unknown];
+  $isNull?: boolean;
+  $not?: WhereCondition;
+  $and?: WhereCondition[];
+  $or?: WhereCondition[];
+  $nor?: WhereCondition[];
+  [key: string]: unknown;
+}
+
+/**
+ * Order by option
+ */
+export interface OrderByOption {
+  field: string;
+  direction: "ASC" | "DESC";
+}
+
+/**
+ * Populate option for resolving references (MongoDB-style)
+ */
+export interface PopulateNested {
+  populate?: PopulateOption;
+  where?: Record<string, unknown>;
+  limit?: number;
+  orderBy?: OrderByOption[];
+}
+
+export type PopulateOption =
+  | string // 'userId categoryIds'
+  | string[] // ['userId', 'categoryIds']
+  | Record<string, boolean | PopulateNested>; // { userId: true, categoryIds: {...} }
+
+/**
+ * Query options
+ */
+export interface QueryOptions {
+  where?: Record<string, unknown>;
+  populate?: PopulateOption;
+  orderBy?: OrderByOption[];
+  limit?: number;
+  offset?: number;
+  lang?: string;
+  fallbackLang?: string;
+}
+
+/**
+ * Paginated result
+ */
+export interface PaginatedResult<T> {
+  data: T[];
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasMore: boolean;
+}
+
+// ==================== ORM Config ====================
+
+/**
+ * ORM Configuration
+ */
+export interface ORMConfig {
+  schema?: SchemaDefinition;
+  defaultLang?: string;
+  fallbackLang?: string;
+}

package/src/utils/jsonConverter.ts

@@ -0,0 +1,94 @@
+/**
+ * JSON Schema Converter
+ *
+ * Bidirectional conversion between JSON schema format and internal SchemaDefinition.
+ * Enables AI agents to work with JSON while maintaining type-safe internal representation.
+ */
+
+import type {
+  JSONSchemaDefinition,
+  JSONFieldDefinition,
+  SchemaDefinition,
+  FieldDefinition,
+  TableDefinition,
+  LanguageConfig,
+} from "../types";
+
+/**
+ * Convert JSON schema to internal SchemaDefinition
+ *
+ * @param json - JSON schema from AI agent or file
+ * @returns Internal SchemaDefinition for processing
+ *
+ * @example
+ * ```typescript
+ * const jsonSchema = {
+ *   name: "products",
+ *   languages: ["en", "tr"],
+ *   tables: {
+ *     products: {
+ *       id: { type: "id", primary: true },
+ *       name: { type: "string", translatable: true, required: true }
+ *     }
+ *   }
+ * };
+ * const schema = parseJSONSchema(jsonSchema);
+ * ```
+ */
+export function parseJSONSchema(json: JSONSchemaDefinition): SchemaDefinition {
+  const languages: LanguageConfig = {
+    default: json.defaultLanguage || json.languages[0] || "en",
+    supported: json.languages || ["en"],
+  };
+
+  const tables: Record<string, TableDefinition> = {};
+
+  for (const [tableName, jsonTable] of Object.entries(json.tables)) {
+    const fields: Record<string, FieldDefinition> = {};
+
+    for (const [fieldName, jsonField] of Object.entries(jsonTable)) {
+      fields[fieldName] = convertJSONField(jsonField);
+    }
+
+    tables[tableName] = {
+      name: tableName,
+      fields,
+    };
+  }
+
+  return {
+    name: json.name,
+    languages,
+    tables,
+  };
+}
+
+/**
+ * Convert single JSON field to internal FieldDefinition
+ */
+function convertJSONField(jsonField: JSONFieldDefinition): FieldDefinition {
+  // Convert ref to FieldReference format
+  let ref: FieldDefinition["ref"];
+  if (jsonField.ref) {
+    if (typeof jsonField.ref === "string") {
+      ref = jsonField.ref;
+    } else {
+      ref = {
+        table: jsonField.ref.table,
+        field: jsonField.ref.field,
+        onDelete: jsonField.ref.onDelete,
+        onUpdate: jsonField.ref.onUpdate,
+      };
+    }
+  }
+
+  return {
+    type: jsonField.type,
+    nullable: jsonField.nullable ?? !jsonField.required,
+    unique: jsonField.unique ?? false,
+    primary: jsonField.primary ?? false,
+    default: jsonField.default,
+    translatable: jsonField.translatable ?? false,
+    ref,
+  };
+}