@promakeai/orm 1.0.1 → 1.0.4

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.d.ts

@@ -47,5 +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 { isJsonType } from "./types";
 export { deserializeRow, serializeRow } from "./utils/deserializer";
-export type { FieldType, FieldDefinition, FieldReference, FieldBuilderLike, TableDefinition, LanguageConfig, SchemaDefinition, SchemaInput, JSONFieldDefinition, JSONTableDefinition, JSONSchemaDefinition, WhereCondition, OrderByOption, PopulateOption, PopulateNested, QueryOptions, PaginatedResult, ORMConfig, } from "./types";
+export type { FieldType, FieldDefinition, FieldReference, FieldBuilderLike, TableDefinition, LanguageConfig, SchemaDefinition, SchemaInput, JSONFieldType, JSONFieldDefinition, JSONTableDefinition, JSONSchemaDefinition, WhereCondition, OrderByOption, PopulateOption, PopulateNested, QueryOptions, PaginatedResult, ORMConfig, } from "./types";

package/dist/index.js

@@ -1,3 +1,8 @@
+// src/types.ts
+function isJsonType(type) {
+  return type === "json" || type === "string[]" || type === "number[]" || type === "boolean[]" || type === "object" || type === "object[]";
+}
+
 // src/utils/populateResolver.ts
 function getRefInfo(fieldName, field) {
   if (!field.ref)
@@ -9,7 +14,7 @@ function getRefInfo(fieldName, field) {
     field: isString ? "id" : ref.field || "id",
     localField: fieldName,
     targetField: isString ? "id" : ref.field || "id",
-    isArray: Array.isArray(field.default) || fieldName.endsWith("Ids")
+    isArray: isJsonType(field.type) || Array.isArray(field.default) || fieldName.endsWith("Ids")
   };
 }
 function toPopulatedName(fieldName) {
@@ -164,7 +169,10 @@ class ORM {
     const { populate, ...queryOpts } = opts;
     let records = await this.adapter.list(table, queryOpts);
     if (populate && this.schema) {
-      records = await this.resolvePopulateForRecords(records, table, populate);
+      records = await this.resolvePopulateForRecords(records, table, populate, {
+        lang: opts.lang,
+        fallbackLang: opts.fallbackLang
+      });
     }
     return records;
   }
@@ -173,7 +181,7 @@ class ORM {
     const { populate, ...queryOpts } = opts;
     const record = await this.adapter.get(table, id, queryOpts);
     if (record && populate && this.schema) {
-      const [populated] = await this.resolvePopulateForRecords([record], table, populate);
+      const [populated] = await this.resolvePopulateForRecords([record], table, populate, { lang: opts.lang, fallbackLang: opts.fallbackLang });
       return populated;
     }
     return record;
@@ -257,7 +265,7 @@ class ORM {
       throw new Error(`Table "${table}" not found in schema`);
     }
   }
-  async resolvePopulateForRecords(records, table, populate) {
+  async resolvePopulateForRecords(records, table, populate, queryOptions) {
     if (!this.schema)
       return records;
     const validation = validatePopulate(populate, table, this.schema);
@@ -266,7 +274,11 @@ class ORM {
     }
     const adapterWrapper = {
       findMany: (t, opts) => {
-        return this.adapter.list(t, opts);
+        return this.adapter.list(t, {
+          ...opts,
+          lang: queryOptions?.lang,
+          fallbackLang: queryOptions?.fallbackLang
+        });
       }
     };
     return resolvePopulate(records, table, populate, this.schema, adapterWrapper);
@@ -299,7 +311,7 @@ function getPrimaryKeyField(table) {
   return entry ? entry[0] : null;
 }
 function getReferenceFields(table) {
-  return Object.entries(table.fields).filter(([_, field]) => field.ref).map(([name, field]) => {
+  return Object.entries(table.fields).filter(([_, field]) => field.ref && !isJsonType(field.type)).map(([name, field]) => {
     const ref = field.ref;
     if (typeof ref === "string") {
       return [name, { table: ref, field: "id" }];
@@ -536,7 +548,20 @@ var f = {
   decimal: () => new FieldBuilder("decimal"),
   bool: () => new FieldBuilder("bool"),
   timestamp: () => new FieldBuilder("timestamp"),
-  json: () => new FieldBuilder("json")
+  json: () => new FieldBuilder("json"),
+  stringArray: () => new FieldBuilder("string[]"),
+  numberArray: () => new FieldBuilder("number[]"),
+  boolArray: () => new FieldBuilder("boolean[]"),
+  object: (properties) => {
+    const builder = new FieldBuilder("object");
+    builder["definition"].properties = properties;
+    return builder;
+  },
+  objectArray: (properties) => {
+    const builder = new FieldBuilder("object[]");
+    builder["definition"].properties = properties;
+    return builder;
+  }
 };
 
 // src/schema/defineSchema.ts
@@ -740,6 +765,20 @@ function processFieldOperators(field, operators) {
       params.push(value[0], value[1]);
     } else if (op === "$isNull") {
       parts.push(value ? `${field} IS NULL` : `${field} IS NOT NULL`);
+    } else if (op === "$contains") {
+      parts.push(`EXISTS (SELECT 1 FROM json_each(${field}) WHERE value = ?)`);
+      params.push(value);
+    } else if (op === "$containsAny") {
+      if (!Array.isArray(value)) {
+        throw new Error("$containsAny operator requires an array value");
+      }
+      if (value.length === 0) {
+        parts.push("0 = 1");
+      } else {
+        const placeholders = value.map(() => "?").join(", ");
+        parts.push(`EXISTS (SELECT 1 FROM json_each(${field}) WHERE value IN (${placeholders}))`);
+        params.push(...value);
+      }
     } else if (op === "$not") {
       if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new Error("$not operator requires an object with operators");
@@ -813,6 +852,7 @@ function buildTranslationQuery(options) {
     schema,
     lang,
     fallbackLang = schema.languages.default,
+    mainFallbackFields,
     where,
     orderBy,
     limit,
@@ -831,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}`);
     }
@@ -876,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
   });
@@ -984,6 +1030,22 @@ function parseJSONSchema(json) {
     tables
   };
 }
+function normalizeJsonType(type) {
+  if (Array.isArray(type)) {
+    const first = type[0];
+    if (typeof first === "string") {
+      const arrayType = `${first}[]`;
+      return { type: arrayType };
+    }
+    if (typeof first === "object" && first !== null) {
+      return { type: "object[]", properties: first };
+    }
+  }
+  if (typeof type === "object" && type !== null && !Array.isArray(type)) {
+    return { type: "object", properties: type };
+  }
+  return { type };
+}
 function convertJSONField(jsonField) {
   let ref;
   if (jsonField.ref) {
@@ -998,13 +1060,15 @@ function convertJSONField(jsonField) {
       };
     }
   }
+  const { type, properties } = normalizeJsonType(jsonField.type);
   return {
-    type: jsonField.type,
+    type,
     nullable: jsonField.nullable ?? !jsonField.required,
     unique: jsonField.unique ?? false,
     primary: jsonField.primary ?? false,
     default: jsonField.default,
     translatable: jsonField.translatable ?? false,
+    properties,
     ref
   };
 }
@@ -1015,7 +1079,7 @@ function deserializeValue(value, fieldType) {
   if (fieldType === "bool") {
     return value === 1 || value === true;
   }
-  if (fieldType === "json" && typeof value === "string") {
+  if (isJsonType(fieldType) && typeof value === "string") {
     try {
       return JSON.parse(value);
     } catch {
@@ -1039,7 +1103,7 @@ function serializeValue(value, fieldType) {
   if (fieldType === "bool") {
     return value ? 1 : 0;
   }
-  if (fieldType === "json" && typeof value !== "string") {
+  if (isJsonType(fieldType) && typeof value !== "string") {
     return JSON.stringify(value);
   }
   return value;
@@ -1073,6 +1137,7 @@ export {
   mergeSchemas,
   isValidSchema,
   isRequiredField,
+  isJsonType,
   hasTranslatableFields,
   getTranslationTableFields,
   getTranslatableFields,

package/dist/schema/fieldBuilder.d.ts

@@ -146,7 +146,43 @@ export declare const f: {
      */
     timestamp: () => FieldBuilder;
     /**
-     * JSON field (TEXT with JSON serialization)
+     * JSON field (TEXT with JSON serialization) — untyped, generates Record<string, unknown>
      */
     json: () => FieldBuilder;
+    /**
+     * String array field — stored as JSON TEXT, generates string[]
+     */
+    stringArray: () => FieldBuilder;
+    /**
+     * Number array field — stored as JSON TEXT, generates number[]
+     */
+    numberArray: () => FieldBuilder;
+    /**
+     * Boolean array field — stored as JSON TEXT, generates boolean[]
+     */
+    boolArray: () => FieldBuilder;
+    /**
+     * Typed object field — stored as JSON TEXT, generates typed interface
+     * @param properties - Property definitions. Keys ending with "?" are optional.
+     *   Values: "string" | "number" | "boolean"
+     *
+     * @example
+     * ```typescript
+     * f.object({ key: "string", value: "number" })
+     * // Generates: { key: string; value: number }
+     * ```
+     */
+    object: (properties: Record<string, string>) => FieldBuilder;
+    /**
+     * Typed object array field — stored as JSON TEXT, generates Array<{...}>
+     * @param properties - Property definitions. Keys ending with "?" are optional.
+     *   Values: "string" | "number" | "boolean"
+     *
+     * @example
+     * ```typescript
+     * f.objectArray({ id: "number", slug: "string", "name?": "string" })
+     * // Generates: Array<{ id: number; slug: string; name?: string }>
+     * ```
+     */
+    objectArray: (properties: Record<string, string>) => FieldBuilder;
 };

package/dist/types.d.ts

@@ -5,8 +5,16 @@
  */
 /**
  * Supported field types
+ *
+ * Primitive types map directly to SQL column types.
+ * Typed JSON types (string[], object[], etc.) store as TEXT in SQL
+ * but generate accurate TypeScript types.
+ */
+export type FieldType = "id" | "string" | "text" | "int" | "decimal" | "bool" | "timestamp" | "json" | "string[]" | "number[]" | "boolean[]" | "object" | "object[]";
+/**
+ * Check if a field type is JSON-like (stored as TEXT in SQL, serialized as JSON)
  */
-export type FieldType = "id" | "string" | "text" | "int" | "decimal" | "bool" | "timestamp" | "json";
+export declare function isJsonType(type: FieldType): boolean;
 /**
  * Foreign key reference definition (MongoDB-style)
  */
@@ -26,6 +34,7 @@ export interface FieldDefinition {
     primary: boolean;
     default?: unknown;
     translatable: boolean;
+    properties?: Record<string, string>;
     ref?: string | FieldReference;
     required?: boolean;
     trim?: boolean;
@@ -74,11 +83,21 @@ export interface SchemaInput {
     languages: string[] | LanguageConfig;
     tables: Record<string, Record<string, FieldBuilderLike>>;
 }
+/**
+ * JSON-native type syntax for schema.json
+ *
+ * Accepts:
+ * - string: primitive type ("string", "int", "json", etc.)
+ * - ["string"]: primitive array
+ * - [{ id: "number", name: "string" }]: typed object array
+ * - { key: "string", value: "number" }: typed object
+ */
+export type JSONFieldType = FieldType | [string] | [Record<string, string>] | Record<string, string>;
 /**
  * JSON Schema Field Definition
  */
 export interface JSONFieldDefinition {
-    type: FieldType;
+    type: JSONFieldType;
     translatable?: boolean;
     required?: boolean;
     unique?: boolean;
@@ -136,6 +155,8 @@ export interface WhereCondition {
     $notLike?: string;
     $between?: [unknown, unknown];
     $isNull?: boolean;
+    $contains?: unknown;
+    $containsAny?: unknown[];
     $not?: WhereCondition;
     $and?: WhereCondition[];
     $or?: WhereCondition[];

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/dist/utils/whereBuilder.d.ts

@@ -12,6 +12,7 @@
  * - Null: $isNull
  * - Negation: $not (field-level)
  * - Logical: $and, $or, $nor
+ * - JSON Array: $contains, $containsAny (for JSON array fields stored as TEXT)
  */
 export interface WhereResult {
     sql: string;

package/package.json

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

package/src/ORM.ts

@@ -100,7 +100,10 @@ export class ORM {
 
     // Resolve populate if schema is available
     if (populate && this.schema) {
-      records = await this.resolvePopulateForRecords(records, table, populate);
+      records = await this.resolvePopulateForRecords(records, table, populate, {
+        lang: opts.lang,
+        fallbackLang: opts.fallbackLang,
+      });
     }
 
     return records;
@@ -132,7 +135,8 @@ export class ORM {
       const [populated] = await this.resolvePopulateForRecords(
         [record],
         table,
-        populate
+        populate,
+        { lang: opts.lang, fallbackLang: opts.fallbackLang }
       );
       return populated;
     }
@@ -346,7 +350,8 @@ export class ORM {
   private async resolvePopulateForRecords<T>(
     records: T[],
     table: string,
-    populate: QueryOptions["populate"]
+    populate: QueryOptions["populate"],
+    queryOptions?: { lang?: string; fallbackLang?: string }
   ): Promise<T[]> {
     if (!this.schema) return records;
 
@@ -356,13 +361,17 @@ export class ORM {
       console.warn("Populate validation warnings:", validation.errors);
     }
 
-    // Create adapter wrapper for populate resolver
+    // Create adapter wrapper for populate resolver (passes lang for translations)
     const adapterWrapper = {
       findMany: <R = unknown>(
         t: string,
         opts?: { where?: Record<string, unknown> }
       ): Promise<R[]> => {
-        return this.adapter.list<R>(t, opts);
+        return this.adapter.list<R>(t, {
+          ...opts,
+          lang: queryOptions?.lang,
+          fallbackLang: queryOptions?.fallbackLang,
+        });
       },
     };
 

package/src/index.ts

@@ -116,6 +116,9 @@ export type { PopulateAdapter } from "./utils/populateResolver";
 // JSON Schema Converter
 export { parseJSONSchema } from "./utils/jsonConverter";
 
+// Type Helpers
+export { isJsonType } from "./types";
+
 // Row Serializer/Deserializer
 export { deserializeRow, serializeRow } from "./utils/deserializer";
 
@@ -134,6 +137,7 @@ export type {
   SchemaInput,
 
   // JSON Schema types (AI-friendly)
+  JSONFieldType,
   JSONFieldDefinition,
   JSONTableDefinition,
   JSONSchemaDefinition,

package/src/schema/fieldBuilder.ts

@@ -237,8 +237,57 @@ export const f = {
   timestamp: (): FieldBuilder => new FieldBuilder("timestamp"),
 
   /**
-   * JSON field (TEXT with JSON serialization)
+   * JSON field (TEXT with JSON serialization) — untyped, generates Record<string, unknown>
    */
   json: (): FieldBuilder => new FieldBuilder("json"),
+
+  /**
+   * String array field — stored as JSON TEXT, generates string[]
+   */
+  stringArray: (): FieldBuilder => new FieldBuilder("string[]"),
+
+  /**
+   * Number array field — stored as JSON TEXT, generates number[]
+   */
+  numberArray: (): FieldBuilder => new FieldBuilder("number[]"),
+
+  /**
+   * Boolean array field — stored as JSON TEXT, generates boolean[]
+   */
+  boolArray: (): FieldBuilder => new FieldBuilder("boolean[]"),
+
+  /**
+   * Typed object field — stored as JSON TEXT, generates typed interface
+   * @param properties - Property definitions. Keys ending with "?" are optional.
+   *   Values: "string" | "number" | "boolean"
+   *
+   * @example
+   * ```typescript
+   * f.object({ key: "string", value: "number" })
+   * // Generates: { key: string; value: number }
+   * ```
+   */
+  object: (properties: Record<string, string>): FieldBuilder => {
+    const builder = new FieldBuilder("object");
+    builder["definition"].properties = properties;
+    return builder;
+  },
+
+  /**
+   * Typed object array field — stored as JSON TEXT, generates Array<{...}>
+   * @param properties - Property definitions. Keys ending with "?" are optional.
+   *   Values: "string" | "number" | "boolean"
+   *
+   * @example
+   * ```typescript
+   * f.objectArray({ id: "number", slug: "string", "name?": "string" })
+   * // Generates: Array<{ id: number; slug: string; name?: string }>
+   * ```
+   */
+  objectArray: (properties: Record<string, string>): FieldBuilder => {
+    const builder = new FieldBuilder("object[]");
+    builder["definition"].properties = properties;
+    return builder;
+  },
 };
 

package/src/schema/schemaHelpers.ts

@@ -5,6 +5,7 @@
  */
 
 import type { TableDefinition, FieldDefinition, FieldReference } from "../types";
+import { isJsonType } from "../types";
 
 /**
  * Get names of translatable fields in a table
@@ -55,7 +56,7 @@ export function getReferenceFields(
   table: TableDefinition
 ): [string, FieldReference][] {
   return Object.entries(table.fields)
-    .filter(([_, field]) => field.ref)
+    .filter(([_, field]) => field.ref && !isJsonType(field.type))
     .map(([name, field]) => {
       const ref = field.ref!;
       // Normalize string to FieldReference

package/src/types.ts

@@ -8,6 +8,10 @@
 
 /**
  * Supported field types
+ *
+ * Primitive types map directly to SQL column types.
+ * Typed JSON types (string[], object[], etc.) store as TEXT in SQL
+ * but generate accurate TypeScript types.
  */
 export type FieldType =
   | "id"
@@ -17,7 +21,19 @@ export type FieldType =
   | "decimal"
   | "bool"
   | "timestamp"
-  | "json";
+  | "json"
+  | "string[]"
+  | "number[]"
+  | "boolean[]"
+  | "object"
+  | "object[]";
+
+/**
+ * Check if a field type is JSON-like (stored as TEXT in SQL, serialized as JSON)
+ */
+export function isJsonType(type: FieldType): boolean {
+  return type === "json" || type === "string[]" || type === "number[]" || type === "boolean[]" || type === "object" || type === "object[]";
+}
 
 /**
  * Foreign key reference definition (MongoDB-style)
@@ -40,6 +56,10 @@ export interface FieldDefinition {
   default?: unknown;
   translatable: boolean;
 
+  // Typed JSON properties (for "object" and "object[]" types)
+  // Keys ending with "?" are optional. Values: "string" | "number" | "boolean"
+  properties?: Record<string, string>;
+
   // Reference (MongoDB-style)
   ref?: string | FieldReference;
 
@@ -101,11 +121,26 @@ export interface SchemaInput {
 
 // ==================== JSON Schema Types (AI Agent Friendly) ====================
 
+/**
+ * JSON-native type syntax for schema.json
+ *
+ * Accepts:
+ * - string: primitive type ("string", "int", "json", etc.)
+ * - ["string"]: primitive array
+ * - [{ id: "number", name: "string" }]: typed object array
+ * - { key: "string", value: "number" }: typed object
+ */
+export type JSONFieldType =
+  | FieldType
+  | [string]
+  | [Record<string, string>]
+  | Record<string, string>;
+
 /**
  * JSON Schema Field Definition
  */
 export interface JSONFieldDefinition {
-  type: FieldType;
+  type: JSONFieldType;
   translatable?: boolean;
   required?: boolean;
   unique?: boolean;
@@ -176,6 +211,8 @@ export interface WhereCondition {
   $notLike?: string;
   $between?: [unknown, unknown];
   $isNull?: boolean;
+  $contains?: unknown;
+  $containsAny?: unknown[];
   $not?: WhereCondition;
   $and?: WhereCondition[];
   $or?: WhereCondition[];

package/src/utils/deserializer.ts

@@ -7,6 +7,7 @@
  */
 
 import type { FieldType, FieldDefinition } from "../types";
+import { isJsonType } from "../types";
 
 /**
  * Deserialize a single value from DB storage type to application type
@@ -18,7 +19,7 @@ function deserializeValue(value: unknown, fieldType: FieldType): unknown {
     return value === 1 || value === true;
   }
 
-  if (fieldType === "json" && typeof value === "string") {
+  if (isJsonType(fieldType) && typeof value === "string") {
     try {
       return JSON.parse(value);
     } catch {
@@ -61,7 +62,7 @@ function serializeValue(value: unknown, fieldType: FieldType): unknown {
     return value ? 1 : 0;
   }
 
-  if (fieldType === "json" && typeof value !== "string") {
+  if (isJsonType(fieldType) && typeof value !== "string") {
     return JSON.stringify(value);
   }
 

package/src/utils/jsonConverter.ts

@@ -8,8 +8,10 @@
 import type {
   JSONSchemaDefinition,
   JSONFieldDefinition,
+  JSONFieldType,
   SchemaDefinition,
   FieldDefinition,
+  FieldType,
   TableDefinition,
   LanguageConfig,
 } from "../types";
@@ -63,6 +65,40 @@ export function parseJSONSchema(json: JSONSchemaDefinition): SchemaDefinition {
   };
 }
 
+/**
+ * Normalize JSON-native type syntax to internal FieldType + properties
+ *
+ * - ["string"]              → type: "string[]"
+ * - ["number"]              → type: "number[]"
+ * - ["boolean"]             → type: "boolean[]"
+ * - [{ id: "number", ... }] → type: "object[]", properties: { id: "number", ... }
+ * - { key: "string", ... }  → type: "object", properties: { key: "string", ... }
+ * - "string" / "json" / ... → pass through as-is
+ */
+function normalizeJsonType(type: JSONFieldType): { type: FieldType; properties?: Record<string, string> } {
+  // Array syntax: ["string"] or [{ ... }]
+  if (Array.isArray(type)) {
+    const first = type[0];
+    if (typeof first === "string") {
+      // Primitive array: ["string"] → "string[]"
+      const arrayType = `${first}[]` as FieldType;
+      return { type: arrayType };
+    }
+    if (typeof first === "object" && first !== null) {
+      // Object array: [{ id: "number", ... }] → "object[]" + properties
+      return { type: "object[]", properties: first as Record<string, string> };
+    }
+  }
+
+  // Object syntax: { key: "string", ... } → "object" + properties
+  if (typeof type === "object" && type !== null && !Array.isArray(type)) {
+    return { type: "object", properties: type as Record<string, string> };
+  }
+
+  // String: pass through as-is
+  return { type: type as FieldType };
+}
+
 /**
  * Convert single JSON field to internal FieldDefinition
  */
@@ -82,13 +118,16 @@ function convertJSONField(jsonField: JSONFieldDefinition): FieldDefinition {
     }
   }
 
+  const { type, properties } = normalizeJsonType(jsonField.type);
+
   return {
-    type: jsonField.type,
+    type,
     nullable: jsonField.nullable ?? !jsonField.required,
     unique: jsonField.unique ?? false,
     primary: jsonField.primary ?? false,
     default: jsonField.default,
     translatable: jsonField.translatable ?? false,
+    properties,
     ref,
   };
 }

package/src/utils/populateResolver.ts

@@ -31,6 +31,7 @@ import type {
   PopulateOption,
   PopulateNested,
 } from "../types";
+import { isJsonType } from "../types";
 
 /**
  * Adapter interface for fetching records
@@ -79,7 +80,7 @@ function getRefInfo(
     field: isString ? "id" : ref.field || "id",
     localField: fieldName,
     targetField: isString ? "id" : ref.field || "id",
-    isArray: Array.isArray(field.default) || fieldName.endsWith("Ids"),
+    isArray: isJsonType(field.type) || Array.isArray(field.default) || fieldName.endsWith("Ids"),
   };
 }
 

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

package/src/utils/whereBuilder.ts

@@ -12,6 +12,7 @@
  * - Null: $isNull
  * - Negation: $not (field-level)
  * - Logical: $and, $or, $nor
+ * - JSON Array: $contains, $containsAny (for JSON array fields stored as TEXT)
  */
 
 export interface WhereResult {
@@ -68,6 +69,22 @@ function processFieldOperators(
       params.push(value[0], value[1]);
     } else if (op === "$isNull") {
       parts.push(value ? `${field} IS NULL` : `${field} IS NOT NULL`);
+    } else if (op === "$contains") {
+      // JSON array contains a single value: EXISTS (SELECT 1 FROM json_each(field) WHERE value = ?)
+      parts.push(`EXISTS (SELECT 1 FROM json_each(${field}) WHERE value = ?)`);
+      params.push(value);
+    } else if (op === "$containsAny") {
+      // JSON array contains any of the values: EXISTS (SELECT 1 FROM json_each(field) WHERE value IN (?, ?))
+      if (!Array.isArray(value)) {
+        throw new Error("$containsAny operator requires an array value");
+      }
+      if (value.length === 0) {
+        parts.push("0 = 1");
+      } else {
+        const placeholders = value.map(() => "?").join(", ");
+        parts.push(`EXISTS (SELECT 1 FROM json_each(${field}) WHERE value IN (${placeholders}))`);
+        params.push(...value);
+      }
     } else if (op === "$not") {
       if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new Error("$not operator requires an object with operators");