@promakeai/orm 1.0.0 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @promakeai/orm
 
-Core ORM package with schema DSL, query builder, and multi-language support.
+Core ORM package with schema DSL, query builder, and multi-language support. Platform-agnostic - works in both browser and Node.js.
 
 ## Installation
 
@@ -15,29 +15,36 @@ import { defineSchema, f } from '@promakeai/orm';
 
 const schema = defineSchema({
   name: 'myapp',
-  languages: ['en', 'tr'],
-  defaultLanguage: 'en',
+  languages: ['en', 'tr', 'de'],
   tables: {
     users: {
       id: f.id(),
-      email: f.string().required().unique(),
-      name: f.string().required(),
-      role: f.string().default('user').enum(['user', 'admin']),
-      createdAt: f.timestamp().default('now'),
+      email: f.string().required().unique().lowercase(),
+      name: f.string().required().trim(),
+      age: f.int().min(0).max(150),
+      role: f.string().enum(['user', 'admin']).default('user'),
+      bio: f.text().translatable(),
+      createdAt: f.timestamp(),
+      metadata: f.json(),
     },
     products: {
       id: f.id(),
       sku: f.string().required().unique(),
-      price: f.decimal().required(),
+      price: f.decimal().required().min(0),
       stock: f.int().default(0),
-      name: f.string().translatable(),        // Multi-language
-      description: f.text().translatable(),   // Multi-language
-      categoryId: f.int().ref('categories'),  // Reference
+      name: f.string().translatable().required(),
+      description: f.text().translatable(),
+      categoryId: f.int().ref('categories'),
+      tagIds: f.json().ref('tags'),  // Array reference
     },
     categories: {
       id: f.id(),
       slug: f.string().required().unique(),
-      name: f.string().translatable(),
+      name: f.string().translatable().required(),
+      parentId: f.int().ref({
+        table: 'categories',
+        onDelete: 'SET_NULL',
+      }),
     },
   },
 });
@@ -45,109 +52,407 @@ const schema = defineSchema({
 
 ## Field Types
 
-| Type | Description |
-|------|-------------|
-| `f.id()` | Auto-increment primary key |
-| `f.string()` | Short text |
-| `f.text()` | Long text |
-| `f.int()` | Integer |
-| `f.decimal()` | Decimal number |
-| `f.bool()` | Boolean |
-| `f.timestamp()` | ISO datetime |
-| `f.json()` | JSON data |
+| Type | SQL | Description |
+|------|-----|-------------|
+| `f.id()` | INTEGER PRIMARY KEY AUTOINCREMENT | Auto-increment primary key |
+| `f.string()` | VARCHAR | Short text |
+| `f.text()` | TEXT | Long text |
+| `f.int()` | INTEGER | Integer |
+| `f.decimal()` | REAL/DECIMAL | Decimal number |
+| `f.bool()` | INTEGER (0/1) | Boolean |
+| `f.timestamp()` | TEXT (ISO) | ISO datetime string |
+| `f.json()` | TEXT | JSON serialized data |
 
 ## Field Modifiers
 
+### Constraints
+
 ```typescript
 f.string()
   .required()              // NOT NULL
+  .nullable()              // Allow NULL (default)
   .unique()                // UNIQUE constraint
-  .default('value')        // Default value
+  .primary()               // PRIMARY KEY
+  .default('value')        // DEFAULT value
+```
+
+### String Transforms
+
+```typescript
+f.string()
+  .trim()                  // Remove whitespace
+  .lowercase()             // Convert to lowercase
+  .uppercase()             // Convert to uppercase
+```
+
+### Validation
+
+```typescript
+f.string()
+  .minLength(1)            // Minimum length
+  .maxLength(255)          // Maximum length
   .enum(['a', 'b', 'c'])   // Allowed values
-  .min(1).max(100)         // Value bounds
-  .translatable()          // Multi-language field
-  .ref('table')            // Reference to another table
-  .ref({ table: 'users', field: 'id', onDelete: 'CASCADE' })
+  .match(/^[a-z]+$/)       // RegExp pattern
+
+f.int()
+  .min(0)                  // Minimum value
+  .max(100)                // Maximum value
+```
+
+### References
+
+```typescript
+// Simple reference
+f.int().ref('users')
+
+// With options
+f.int().ref({
+  table: 'users',
+  field: 'id',             // Default: 'id'
+  onDelete: 'CASCADE',     // CASCADE | SET_NULL | RESTRICT | NO_ACTION
+  onUpdate: 'CASCADE',
+})
+
+// Array reference (JSON field with refs)
+f.json().ref('tags')
+```
+
+### Multi-Language
+
+```typescript
+f.string().translatable()  // Stored in {table}_translations
+f.text().translatable()
 ```
 
 ## Query Builder (MongoDB-style)
 
 ```typescript
-import { buildWhere } from '@promakeai/orm';
+import { buildWhereClause } from '@promakeai/orm';
 
 // Simple equality
-buildWhere({ status: 'active' });
-// WHERE status = 'active'
+buildWhereClause({ status: 'active' });
+// WHERE status = ?  params: ['active']
 
 // Comparison operators
-buildWhere({ price: { $gt: 100 } });           // > 100
-buildWhere({ price: { $gte: 100 } });          // >= 100
-buildWhere({ price: { $lt: 100 } });           // < 100
-buildWhere({ price: { $lte: 100 } });          // <= 100
-buildWhere({ status: { $ne: 'deleted' } });    // != 'deleted'
+buildWhereClause({ price: { $gt: 100 } });    // > 100
+buildWhereClause({ price: { $gte: 100 } });   // >= 100
+buildWhereClause({ price: { $lt: 100 } });    // < 100
+buildWhereClause({ price: { $lte: 100 } });   // <= 100
+buildWhereClause({ status: { $ne: 'deleted' } }); // != 'deleted'
 
 // Array operators
-buildWhere({ id: { $in: [1, 2, 3] } });        // IN (1, 2, 3)
-buildWhere({ id: { $nin: [1, 2, 3] } });       // NOT IN (1, 2, 3)
+buildWhereClause({ id: { $in: [1, 2, 3] } });    // IN (?, ?, ?)
+buildWhereClause({ id: { $nin: [1, 2, 3] } });   // NOT IN (?, ?, ?)
 
 // String matching
-buildWhere({ name: { $like: '%john%' } });     // LIKE '%john%'
-buildWhere({ name: { $notLike: '%test%' } });  // NOT LIKE '%test%'
+buildWhereClause({ name: { $like: '%john%' } });     // LIKE ?
+buildWhereClause({ name: { $notLike: '%test%' } });  // NOT LIKE ?
 
 // Range and null
-buildWhere({ price: { $between: [10, 100] } }); // BETWEEN 10 AND 100
-buildWhere({ deletedAt: { $isNull: true } });   // IS NULL
-buildWhere({ email: { $isNull: false } });      // IS NOT NULL
+buildWhereClause({ price: { $between: [10, 100] } }); // BETWEEN ? AND ?
+buildWhereClause({ deletedAt: { $isNull: true } });   // IS NULL
+buildWhereClause({ email: { $isNull: false } });      // IS NOT NULL
 
 // Logical operators
-buildWhere({ $or: [{ active: true }, { role: 'admin' }] });
-buildWhere({ $and: [{ price: { $gt: 50 } }, { stock: { $gt: 0 } }] });
-buildWhere({ $nor: [{ banned: true }, { suspended: true }] });
+buildWhereClause({
+  $or: [
+    { active: true },
+    { role: 'admin' }
+  ]
+});
+// (active = ? OR role = ?)
+
+buildWhereClause({
+  $and: [
+    { price: { $gt: 50 } },
+    { stock: { $gt: 0 } }
+  ]
+});
+// (price > ? AND stock > ?)
+
+buildWhereClause({
+  $nor: [
+    { banned: true },
+    { suspended: true }
+  ]
+});
+// NOT (banned = ? OR suspended = ?)
+
+// Negation
+buildWhereClause({
+  age: { $not: { $lt: 18 } }
+});
+// NOT (age < ?)
+
+// Combined
+buildWhereClause({
+  status: 'active',
+  price: { $gt: 100, $lt: 500 },
+  category: { $in: ['electronics', 'books'] },
+});
+// status = ? AND price > ? AND price < ? AND category IN (?, ?)
 ```
 
 ## Multi-Language Support
 
-Schema fields marked with `.translatable()` are stored in separate translation tables:
+### Schema Configuration
 
 ```typescript
-// Schema
-products: {
-  id: f.id(),
-  price: f.decimal(),
-  name: f.string().translatable(),      // Stored in products_translations
-  description: f.text().translatable(), // Stored in products_translations
-}
+const schema = defineSchema({
+  languages: ['en', 'tr', 'de'],  // Supported languages
+  // OR
+  languages: {
+    default: 'en',
+    supported: ['en', 'tr', 'de'],
+  },
+  tables: {
+    products: {
+      id: f.id(),
+      price: f.decimal(),
+      name: f.string().translatable(),      // In translation table
+      description: f.text().translatable(), // In translation table
+    },
+  },
+});
+```
+
+### Generated Tables
+
+```sql
+-- Main table
+CREATE TABLE products (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  price REAL
+);
 
-// Creates tables:
-// - products (id, price)
-// - products_translations (id, product_id, lang, name, description)
+-- Translation table
+CREATE TABLE products_translations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  product_id INTEGER NOT NULL,
+  lang TEXT NOT NULL,
+  name TEXT,
+  description TEXT,
+  FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE,
+  UNIQUE (product_id, lang)
+);
 ```
 
-Query with language:
+### Translation Query Builder
 
 ```typescript
-const products = await dm.query('products', {
+import { buildTranslationQuery } from '@promakeai/orm';
+
+const { sql, params } = buildTranslationQuery('products', schema, {
   lang: 'tr',
-  fallbackLang: 'en',  // Falls back if translation missing
+  fallbackLang: 'en',
+  where: { price: { $gt: 100 } },
+  orderBy: [{ field: 'name', direction: 'ASC' }],
+  limit: 10,
 });
+
+// SELECT
+//   m.id, m.price,
+//   COALESCE(t.name, fb.name) AS name,
+//   COALESCE(t.description, fb.description) AS description
+// FROM products m
+// LEFT JOIN products_translations t ON m.id = t.product_id AND t.lang = ?
+// LEFT JOIN products_translations fb ON m.id = fb.product_id AND fb.lang = ?
+// WHERE price > ?
+// ORDER BY name ASC
+// LIMIT 10
+```
+
+## Populate Resolver
+
+Batch-fetches references to prevent N+1 queries:
+
+```typescript
+import { resolvePopulate } from '@promakeai/orm';
+
+const posts = await adapter.list('posts');
+
+// Resolve author references
+const postsWithAuthors = await resolvePopulate(
+  posts,
+  { userId: true },
+  schema,
+  adapter
+);
+// [{ id: 1, title: '...', userId: { id: 1, name: 'John' } }]
+
+// Nested populate
+const postsWithDetails = await resolvePopulate(
+  posts,
+  {
+    userId: true,
+    comments: {
+      populate: { authorId: true },
+      where: { approved: true },
+      limit: 5,
+    },
+  },
+  schema,
+  adapter
+);
+
+// Array reference populate
+const postsWithTags = await resolvePopulate(
+  posts,
+  { tagIds: true },  // JSON array of tag IDs
+  schema,
+  adapter
+);
+```
+
+## Schema Helpers
+
+```typescript
+import {
+  getTranslatableFields,
+  getNonTranslatableFields,
+  getReferenceFields,
+  getPrimaryKeyField,
+  getRequiredFields,
+  isRequiredField,
+  getMainTableFields,
+  getTranslationTableFields,
+  toTranslationTableName,
+  toTranslationFKName,
+  singularize,
+  pluralize,
+  toPascalCase,
+  toCamelCase,
+  toSnakeCase,
+} from '@promakeai/orm';
+
+const table = schema.tables.products;
+
+getTranslatableFields(table);    // ['name', 'description']
+getNonTranslatableFields(table); // ['id', 'price', 'sku', 'stock', 'categoryId']
+getReferenceFields(table);       // [['categoryId', { table: 'categories', ... }]]
+getPrimaryKeyField(table);       // 'id'
+getRequiredFields(table);        // ['sku', 'price', 'name']
+
+toTranslationTableName('products');  // 'products_translations'
+toTranslationFKName('products');     // 'product_id'
+
+singularize('products');  // 'product'
+pluralize('product');     // 'products'
+toPascalCase('user_id');  // 'UserId'
+toCamelCase('user_id');   // 'userId'
+toSnakeCase('userId');    // 'user_id'
+```
+
+## Schema Validation
+
+```typescript
+import {
+  validateSchema,
+  assertValidSchema,
+  isValidSchema,
+} from '@promakeai/orm';
+
+// Returns array of errors
+const errors = validateSchema(schema);
+// [{ path: 'tables.users.email', message: '...' }]
+
+// Throws on invalid schema
+assertValidSchema(schema);
+
+// Boolean check
+if (isValidSchema(schema)) {
+  // ...
+}
+```
+
+## Schema Merging
+
+```typescript
+import { mergeSchemas } from '@promakeai/orm';
+
+const schema1 = defineSchema({
+  tables: { users: { ... } },
+});
+
+const schema2 = defineSchema({
+  tables: { products: { ... } },
+});
+
+const merged = mergeSchemas([schema1, schema2]);
+// { tables: { users: {...}, products: {...} } }
+```
+
+## IDataAdapter Interface
+
+All adapters must implement this interface:
+
+```typescript
+interface IDataAdapter {
+  schema?: SchemaDefinition;
+  defaultLang?: string;
+
+  // Query methods
+  list<T>(table: string, options?: QueryOptions): Promise<T[]>;
+  get<T>(table: string, id: string | number, options?: QueryOptions): Promise<T | null>;
+  count(table: string, options?: QueryOptions): Promise<number>;
+  paginate<T>(table: string, page: number, limit: number, options?: QueryOptions): Promise<PaginatedResult<T>>;
+
+  // Write methods
+  create<T>(table: string, data: Record<string, unknown>): Promise<T>;
+  update<T>(table: string, id: string | number, data: Record<string, unknown>): Promise<T>;
+  delete(table: string, id: string | number): Promise<boolean>;
+
+  // Batch methods
+  createMany<T>(table: string, records: Record<string, unknown>[], options?: { ignore?: boolean }): Promise<{ created: number; ids: (number | bigint)[] }>;
+  updateMany(table: string, updates: { id: number | string; data: Record<string, unknown> }[]): Promise<{ updated: number }>;
+  deleteMany(table: string, ids: (number | string)[]): Promise<{ deleted: number }>;
+
+  // Translation methods
+  createWithTranslations<T>(table: string, data: Record<string, unknown>, translations?: Record<string, Record<string, unknown>>): Promise<T>;
+  upsertTranslation(table: string, id: string | number, lang: string, data: Record<string, unknown>): Promise<void>;
+  getTranslations<T>(table: string, id: string | number): Promise<T[]>;
+
+  // Raw queries
+  raw<T>(query: string, params?: unknown[]): Promise<T[]>;
+  execute(query: string, params?: unknown[]): Promise<{ changes: number; lastInsertRowid: number | bigint }>;
+
+  // Transactions
+  beginTransaction(): Promise<void>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+
+  // Schema
+  getTables?(): Promise<string[]>;
+  getTableSchema?(table: string): Promise<unknown[]>;
+
+  // Lifecycle
+  connect?(): void | Promise<void>;
+  close(): void | Promise<void>;
+}
 ```
 
-## Types
+## TypeScript Types
 
 ```typescript
 import type {
-  Schema,
+  SchemaDefinition,
   TableDefinition,
   FieldDefinition,
+  FieldType,
+  FieldReference,
   QueryOptions,
   WhereClause,
+  OrderByOption,
+  PopulateOption,
+  PaginatedResult,
+  IDataAdapter,
 } from '@promakeai/orm';
 ```
 
 ## Related Packages
 
-- [@promakeai/dbcli](../dbcli) - CLI tool
-- [@promakeai/dbreact](../dbreact) - React integration
+- [@promakeai/dbcli](../dbcli) - CLI tool for database operations
+- [@promakeai/dbreact](../dbreact) - React hooks and providers
 
 ## License
 

package/dist/adapters/IDataAdapter.d.ts

@@ -38,6 +38,10 @@ export interface IDataAdapter {
      * Get single record by ID
      */
     get<T = unknown>(table: string, id: string | number, options?: QueryOptions): Promise<T | null>;
+    /**
+     * Find first record matching query (like Mongoose findOne)
+     */
+    findOne<T = unknown>(table: string, options?: QueryOptions): Promise<T | null>;
     /**
      * Count records matching condition
      */

package/dist/index.d.ts

@@ -47,4 +47,6 @@ export type { TranslationQueryOptions, TranslationQueryResult, } from "./utils/t
 export { resolvePopulate, getPopulatableFields, validatePopulate, } from "./utils/populateResolver";
 export type { PopulateAdapter } from "./utils/populateResolver";
 export { parseJSONSchema } from "./utils/jsonConverter";
-export type { FieldType, FieldDefinition, FieldReference, FieldBuilderLike, TableDefinition, LanguageConfig, SchemaDefinition, SchemaInput, JSONFieldDefinition, JSONTableDefinition, JSONSchemaDefinition, WhereCondition, OrderByOption, PopulateOption, PopulateNested, QueryOptions, PaginatedResult, ORMConfig, } from "./types";
+export { isJsonType } from "./types";
+export { deserializeRow, serializeRow } from "./utils/deserializer";
+export type { FieldType, FieldDefinition, FieldReference, FieldBuilderLike, TableDefinition, LanguageConfig, SchemaDefinition, SchemaInput, JSONFieldType, JSONFieldDefinition, JSONTableDefinition, JSONSchemaDefinition, WhereCondition, OrderByOption, PopulateOption, PopulateNested, QueryOptions, PaginatedResult, ORMConfig, } from "./types";