@promakeai/orm 1.0.0

package/dist/schema/defineSchema.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 } from "../types";
+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 declare function defineSchema(input: SchemaInput): SchemaDefinition;
+/**
+ * Create schema without validation (for testing/internal use)
+ * @internal
+ */
+export declare function createSchemaUnsafe(input: SchemaInput): SchemaDefinition;
+/**
+ * Merge multiple schemas into one
+ *
+ * @param schemas - Array of schema definitions to merge
+ * @returns Merged schema definition
+ * @throws Error if table names conflict
+ */
+export declare function mergeSchemas(schemas: SchemaDefinition[]): SchemaDefinition;

package/dist/schema/fieldBuilder.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 } from "../types";
+/**
+ * Fluent builder for field definitions
+ */
+export declare class FieldBuilder {
+    protected definition: FieldDefinition;
+    constructor(type: FieldType);
+    /**
+     * Mark field as NOT NULL
+     */
+    required(): this;
+    /**
+     * Mark field as nullable (default)
+     */
+    nullable(): this;
+    /**
+     * Mark field as UNIQUE
+     */
+    unique(): this;
+    /**
+     * Set default value
+     */
+    default(value: unknown): this;
+    /**
+     * Mark field as translatable (stored in translation table)
+     * Only valid for string/text fields
+     */
+    translatable(): 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;
+    /**
+     * Trim whitespace from string values
+     */
+    trim(): this;
+    /**
+     * Convert string to lowercase
+     */
+    lowercase(): this;
+    /**
+     * Convert string to uppercase
+     */
+    uppercase(): this;
+    /**
+     * Minimum string length
+     */
+    minLength(value: number): this;
+    /**
+     * Maximum string length
+     */
+    maxLength(value: number): this;
+    /**
+     * Minimum numeric value
+     */
+    min(value: number): this;
+    /**
+     * Maximum numeric value
+     */
+    max(value: number): this;
+    /**
+     * Enum values (allowed values)
+     */
+    enum(values: string[]): this;
+    /**
+     * RegExp pattern to match
+     */
+    match(pattern: string): this;
+    /**
+     * Build the final field definition
+     * @internal
+     */
+    build(): FieldDefinition;
+}
+/**
+ * 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 declare const f: {
+    /**
+     * Primary key field (INTEGER PRIMARY KEY AUTOINCREMENT)
+     */
+    id: () => FieldBuilder;
+    /**
+     * String field (VARCHAR/TEXT)
+     */
+    string: () => FieldBuilder;
+    /**
+     * Text field (TEXT/LONGTEXT)
+     */
+    text: () => FieldBuilder;
+    /**
+     * Integer field (INTEGER)
+     */
+    int: () => FieldBuilder;
+    /**
+     * Decimal field (REAL/DECIMAL)
+     */
+    decimal: () => FieldBuilder;
+    /**
+     * Boolean field (INTEGER 0/1 in SQLite)
+     */
+    bool: () => FieldBuilder;
+    /**
+     * Timestamp field (TEXT in ISO format)
+     */
+    timestamp: () => FieldBuilder;
+    /**
+     * JSON field (TEXT with JSON serialization)
+     */
+    json: () => FieldBuilder;
+};

package/dist/schema/helpers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare function singularize(word: string): string;
+/**
+ * Convert string to PascalCase
+ */
+export declare function toPascalCase(str: string): string;
+/**
+ * Convert string to camelCase
+ */
+export declare function toCamelCase(str: string): string;
+/**
+ * Convert string to snake_case
+ */
+export declare function toSnakeCase(str: string): string;
+/**
+ * Get singular PascalCase name for interface
+ */
+export declare function toInterfaceName(tableName: string): string;
+/**
+ * Get Db-prefixed interface name
+ * @example toDbInterfaceName('products') // 'DbProduct'
+ */
+export declare function toDbInterfaceName(tableName: string): string;
+/**
+ * Pluralize a word (basic implementation)
+ */
+export declare function pluralize(word: string): string;
+/**
+ * Get PascalCase plural form
+ * @example toPascalCasePlural('products') // 'Products'
+ */
+export declare function toPascalCasePlural(tableName: string): string;
+/**
+ * Get translation table name
+ */
+export declare function toTranslationTableName(tableName: string): string;
+/**
+ * Get foreign key column name for translation table
+ */
+export declare function toTranslationFKName(tableName: string): string;

package/dist/schema/index.d.ts

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

package/dist/schema/schemaHelpers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare function getTranslatableFields(table: TableDefinition): string[];
+/**
+ * Get names of non-translatable fields in a table (excluding primary key)
+ */
+export declare function getNonTranslatableFields(table: TableDefinition): string[];
+/**
+ * Get all non-primary key fields (for INSERT statements)
+ */
+export declare function getInsertableFields(table: TableDefinition): string[];
+/**
+ * Check if table has any translatable fields
+ */
+export declare function hasTranslatableFields(table: TableDefinition): boolean;
+/**
+ * Get the primary key field name
+ */
+export declare function getPrimaryKeyField(table: TableDefinition): string | null;
+/**
+ * Get fields with foreign key references (using ref)
+ */
+export declare function getReferenceFields(table: TableDefinition): [string, FieldReference][];
+/**
+ * Get fields for main table (excluding translatable)
+ */
+export declare function getMainTableFields(table: TableDefinition): [string, FieldDefinition][];
+/**
+ * Get fields for translation table
+ */
+export declare function getTranslationTableFields(table: TableDefinition): [string, FieldDefinition][];
+/**
+ * Check if a field is required (NOT NULL without default)
+ */
+export declare function isRequiredField(field: FieldDefinition): boolean;
+/**
+ * Get required fields for input validation
+ */
+export declare function getRequiredFields(table: TableDefinition): string[];
+/**
+ * Get reference target table name from field
+ */
+export declare function getRefTarget(field: FieldDefinition): string | null;
+/**
+ * Get full reference target (table and field) from field
+ * Returns { table, field } object
+ */
+export declare function getRefTargetFull(field: FieldDefinition): FieldReference | null;

package/dist/schema/validator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Schema Validator
+ *
+ * Validates schema definitions for correctness.
+ */
+import type { SchemaDefinition, TableDefinition } from "../types";
+/**
+ * Validation error with context
+ */
+export interface ValidationError {
+    table: string;
+    field?: string;
+    message: string;
+    code: string;
+}
+/**
+ * Error codes for validation
+ */
+export declare const ValidationErrorCode: {
+    readonly MISSING_PRIMARY_KEY: "MISSING_PRIMARY_KEY";
+    readonly INVALID_REFERENCE: "INVALID_REFERENCE";
+    readonly INVALID_TRANSLATABLE_TYPE: "INVALID_TRANSLATABLE_TYPE";
+    readonly NO_LANGUAGES: "NO_LANGUAGES";
+    readonly DUPLICATE_TABLE: "DUPLICATE_TABLE";
+    readonly RESERVED_FIELD_NAME: "RESERVED_FIELD_NAME";
+    readonly SELF_REFERENCE_ON_REQUIRED: "SELF_REFERENCE_ON_REQUIRED";
+};
+/**
+ * Validate a schema definition
+ *
+ * @returns Array of validation errors (empty if valid)
+ */
+export declare function validateSchema(schema: SchemaDefinition): ValidationError[];
+/**
+ * Validate schema and throw if invalid
+ */
+export declare function assertValidSchema(schema: SchemaDefinition): void;
+/**
+ * Check if schema is valid (returns boolean)
+ */
+export declare function isValidSchema(schema: SchemaDefinition): boolean;
+/**
+ * Validate a single table definition
+ */
+export declare function validateTable(tableName: string, table: TableDefinition, allTableNames: string[]): ValidationError[];

package/dist/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @promakeai/orm Core Type Definitions
+ *
+ * Database-agnostic types that work in browser and Node.js
+ */
+/**
+ * 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;
+    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;
+    ref?: string | FieldReference;
+    required?: boolean;
+    trim?: boolean;
+    lowercase?: boolean;
+    uppercase?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    enum?: string[];
+    match?: string;
+}
+/**
+ * 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 Field Definition
+ */
+export interface JSONFieldDefinition {
+    type: FieldType;
+    translatable?: boolean;
+    required?: boolean;
+    unique?: boolean;
+    primary?: boolean;
+    nullable?: boolean;
+    default?: unknown;
+    precision?: number;
+    scale?: number;
+    min?: number;
+    max?: number;
+    trim?: boolean;
+    lowercase?: boolean;
+    uppercase?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    enum?: string[];
+    match?: string;
+    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;
+    };
+}
+/**
+ * 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 | string[] | Record<string, boolean | PopulateNested>;
+/**
+ * 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 Configuration
+ */
+export interface ORMConfig {
+    schema?: SchemaDefinition;
+    defaultLang?: string;
+    fallbackLang?: string;
+}

package/dist/utils/jsonConverter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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, SchemaDefinition } 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 declare function parseJSONSchema(json: JSONSchemaDefinition): SchemaDefinition;

package/dist/utils/populateResolver.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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, PopulateOption } 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[]>;
+}
+/**
+ * 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 declare function resolvePopulate<T>(records: T[], table: string, populate: PopulateOption | undefined, schema: SchemaDefinition, adapter: PopulateAdapter): Promise<T[]>;
+/**
+ * Get all populatable fields from a table
+ */
+export declare function getPopulatableFields(tableDef: TableDefinition): string[];
+/**
+ * Validate populate options against schema
+ */
+export declare function validatePopulate(populate: PopulateOption | undefined, table: string, schema: SchemaDefinition): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/utils/translationQuery.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Translation Query Builder
+ *
+ * Build SQL queries with automatic translation table joins
+ * and COALESCE for language fallback.
+ */
+import type { SchemaDefinition, TableDefinition, OrderByOption } from "../types";
+/**
+ * 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 declare function buildTranslationQuery(options: TranslationQueryOptions): TranslationQueryResult;
+/**
+ * Build query for single record by ID with translations
+ */
+export declare function buildTranslationQueryById(table: string, schema: SchemaDefinition, id: number | string, lang: string, fallbackLang?: string): TranslationQueryResult;
+/**
+ * Build INSERT statement for translation
+ */
+export declare function buildTranslationInsert(table: string, schema: SchemaDefinition, recordId: number | string, lang: string, data: Record<string, unknown>): TranslationQueryResult;
+/**
+ * Build UPSERT statement for translation (INSERT OR REPLACE)
+ */
+export declare function buildTranslationUpsert(table: string, schema: SchemaDefinition, recordId: number | string, lang: string, data: Record<string, unknown>): TranslationQueryResult;
+/**
+ * Extract translatable fields from data object
+ */
+export declare function extractTranslatableData(data: Record<string, unknown>, tableSchema: TableDefinition): {
+    mainData: Record<string, unknown>;
+    translatableData: Record<string, unknown>;
+};