@promakeai/orm 1.0.3 → 1.0.5

package/README.md

@@ -13,9 +13,9 @@ npm install @promakeai/orm
 ```typescript
 import { defineSchema, f } from '@promakeai/orm';
 
-const schema = defineSchema({
-  name: 'myapp',
-  languages: ['en', 'tr', 'de'],
+const schema = defineSchema({
+  name: 'myapp',
+  languages: ['en', 'tr', 'de'],
   tables: {
     users: {
       id: f.id(),
@@ -47,21 +47,45 @@ const schema = defineSchema({
       }),
     },
   },
-});
-```
-
-## Field Types
-
-| 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 |
+});
+```
+
+## JSON Schema (AI-Friendly)
+
+The JSON schema format is the runtime-friendly version and supports native
+arrays and typed objects:
+
+```json
+{
+  "name": "myapp",
+  "languages": ["en", "tr"],
+  "defaultLanguage": "en",
+  "tables": {
+    "products": {
+      "id": { "type": "id" },
+      "tags": { "type": ["string"] },
+      "metadata": { "type": { "color": "string", "weight": "number" } },
+      "variants": { "type": [{ "sku": "string", "price": "number" }] }
+    }
+  }
+}
+```
+
+## Field Types
+
+| 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 |
+
+JSON schema type syntax supports `string[]`, `number[]`, `boolean[]`, `object`,
+and `object[]` which are stored as JSON in SQL (TEXT) and typed in TS.
 
 ## Field Modifiers
 
@@ -148,10 +172,14 @@ buildWhereClause({ id: { $nin: [1, 2, 3] } });   // NOT IN (?, ?, ?)
 buildWhereClause({ name: { $like: '%john%' } });     // LIKE ?
 buildWhereClause({ name: { $notLike: '%test%' } });  // NOT LIKE ?
 
-// Range and null
-buildWhereClause({ price: { $between: [10, 100] } }); // BETWEEN ? AND ?
-buildWhereClause({ deletedAt: { $isNull: true } });   // IS NULL
-buildWhereClause({ email: { $isNull: false } });      // IS NOT NULL
+// Range and null
+buildWhereClause({ price: { $between: [10, 100] } }); // BETWEEN ? AND ?
+buildWhereClause({ deletedAt: { $isNull: true } });   // IS NULL
+buildWhereClause({ email: { $isNull: false } });      // IS NOT NULL
+
+// JSON array contains
+buildWhereClause({ tags: { $contains: "sale" } });    // json_each(...) = "sale"
+buildWhereClause({ tags: { $containsAny: ["sale", "new"] } }); // json_each(...) IN (...)
 
 // Logical operators
 buildWhereClause({
@@ -262,9 +290,12 @@ const { sql, params } = buildTranslationQuery('products', schema, {
 // LIMIT 10
 ```
 
-## Populate Resolver
-
-Batch-fetches references to prevent N+1 queries:
+## Populate Resolver
+
+Batch-fetches references to prevent N+1 queries:
+
+Populate options accept a space-separated string, string array, or nested object
+for deeper population.
 
 ```typescript
 import { resolvePopulate } from '@promakeai/orm';

package/dist/index.js

@@ -852,6 +852,7 @@ function buildTranslationQuery(options) {
     schema,
     lang,
     fallbackLang = schema.languages.default,
+    mainFallbackFields,
     where,
     orderBy,
     limit,
@@ -870,10 +871,15 @@ function buildTranslationQuery(options) {
   const mainAlias = "m";
   const transAlias = "t";
   const fallbackAlias = "fb";
+  const mainFallbackSet = mainFallbackFields !== undefined ? new Set(mainFallbackFields) : null;
   const selectFields = [];
   for (const [fieldName, field] of Object.entries(tableSchema.fields)) {
     if (field.translatable) {
-      selectFields.push(`COALESCE(${transAlias}.${fieldName}, ${fallbackAlias}.${fieldName}) as ${fieldName}`);
+      if (mainFallbackSet && !mainFallbackSet.has(fieldName)) {
+        selectFields.push(`COALESCE(${transAlias}.${fieldName}, ${fallbackAlias}.${fieldName}) as ${fieldName}`);
+      } else {
+        selectFields.push(`COALESCE(${transAlias}.${fieldName}, ${fallbackAlias}.${fieldName}, ${mainAlias}.${fieldName}) as ${fieldName}`);
+      }
     } else {
       selectFields.push(`${mainAlias}.${fieldName}`);
     }
@@ -915,12 +921,13 @@ OFFSET ?`;
   }
   return { sql, params };
 }
-function buildTranslationQueryById(table, schema, id, lang, fallbackLang) {
+function buildTranslationQueryById(table, schema, id, lang, fallbackLang, mainFallbackFields) {
   return buildTranslationQuery({
     table,
     schema,
     lang,
     fallbackLang,
+    mainFallbackFields,
     where: { id },
     limit: 1
   });

package/dist/utils/translationQuery.d.ts

@@ -13,6 +13,11 @@ export interface TranslationQueryOptions {
     schema: SchemaDefinition;
     lang: string;
     fallbackLang?: string;
+    /**
+     * Main-table fields that can be safely used as cache fallback in COALESCE.
+     * If omitted, all translatable fields are assumed available in main table.
+     */
+    mainFallbackFields?: string[];
     where?: Record<string, unknown>;
     orderBy?: OrderByOption[];
     limit?: number;
@@ -32,7 +37,7 @@ export declare function buildTranslationQuery(options: TranslationQueryOptions):
 /**
  * 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;
+export declare function buildTranslationQueryById(table: string, schema: SchemaDefinition, id: number | string, lang: string, fallbackLang?: string, mainFallbackFields?: string[]): TranslationQueryResult;
 /**
  * Build INSERT statement for translation
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promakeai/orm",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Database-agnostic ORM core - works in browser and Node.js",
   "type": "module",
   "main": "./dist/index.js",

package/src/utils/translationQuery.ts

@@ -44,16 +44,21 @@ function buildAliasedWhereClause(
 /**
  * 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;
-}
+export interface TranslationQueryOptions {
+  table: string;
+  schema: SchemaDefinition;
+  lang: string;
+  fallbackLang?: string;
+  /**
+   * Main-table fields that can be safely used as cache fallback in COALESCE.
+   * If omitted, all translatable fields are assumed available in main table.
+   */
+  mainFallbackFields?: string[];
+  where?: Record<string, unknown>;
+  orderBy?: OrderByOption[];
+  limit?: number;
+  offset?: number;
+}
 
 /**
  * Query result with SQL and parameters
@@ -73,12 +78,13 @@ export function buildTranslationQuery(
     table,
     schema,
     lang,
-    fallbackLang = schema.languages.default,
-    where,
-    orderBy,
-    limit,
-    offset,
-  } = options;
+    fallbackLang = schema.languages.default,
+    mainFallbackFields,
+    where,
+    orderBy,
+    limit,
+    offset,
+  } = options;
 
   const tableSchema = schema.tables[table];
   if (!tableSchema) {
@@ -94,22 +100,32 @@ export function buildTranslationQuery(
   const transTable = toTranslationTableName(table);
   const fkName = toTranslationFKName(table);
 
-  const mainAlias = "m";
-  const transAlias = "t";
-  const fallbackAlias = "fb";
+  const mainAlias = "m";
+  const transAlias = "t";
+  const fallbackAlias = "fb";
+  const mainFallbackSet =
+    mainFallbackFields !== undefined
+      ? new Set(mainFallbackFields)
+      : null;
 
   // Build SELECT fields
   const selectFields: string[] = [];
 
-  for (const [fieldName, field] of Object.entries(tableSchema.fields)) {
-    if (field.translatable) {
-      selectFields.push(
-        `COALESCE(${transAlias}.${fieldName}, ${fallbackAlias}.${fieldName}) as ${fieldName}`
-      );
-    } else {
-      selectFields.push(`${mainAlias}.${fieldName}`);
-    }
-  }
+  for (const [fieldName, field] of Object.entries(tableSchema.fields)) {
+    if (field.translatable) {
+      if (mainFallbackSet && !mainFallbackSet.has(fieldName)) {
+        selectFields.push(
+          `COALESCE(${transAlias}.${fieldName}, ${fallbackAlias}.${fieldName}) as ${fieldName}`
+        );
+      } else {
+        selectFields.push(
+          `COALESCE(${transAlias}.${fieldName}, ${fallbackAlias}.${fieldName}, ${mainAlias}.${fieldName}) as ${fieldName}`
+        );
+      }
+    } else {
+      selectFields.push(`${mainAlias}.${fieldName}`);
+    }
+  }
 
   let sql = `SELECT ${selectFields.join(", ")}
 FROM ${table} ${mainAlias}
@@ -154,22 +170,24 @@ LEFT JOIN ${transTable} ${fallbackAlias}
 /**
  * Build query for single record by ID with translations
  */
-export function buildTranslationQueryById(
-  table: string,
-  schema: SchemaDefinition,
-  id: number | string,
-  lang: string,
-  fallbackLang?: string
-): TranslationQueryResult {
-  return buildTranslationQuery({
-    table,
-    schema,
-    lang,
-    fallbackLang,
-    where: { id },
-    limit: 1,
-  });
-}
+export function buildTranslationQueryById(
+  table: string,
+  schema: SchemaDefinition,
+  id: number | string,
+  lang: string,
+  fallbackLang?: string,
+  mainFallbackFields?: string[]
+): TranslationQueryResult {
+  return buildTranslationQuery({
+    table,
+    schema,
+    lang,
+    fallbackLang,
+    mainFallbackFields,
+    where: { id },
+    limit: 1,
+  });
+}
 
 /**
  * Build simple query without translations