@promakeai/orm 1.0.6 → 1.3.0

package/src/schema/validator.ts

@@ -4,9 +4,12 @@
  * Validates schema definitions for correctness.
  */
 
-import type { SchemaDefinition, TableDefinition } from "../types";
+import type { SchemaDefinition, TableDefinition, PermissionRole, PermissionAction } from "../types";
 import { getRefTarget } from "./schemaHelpers";
 
+const VALID_ROLES: PermissionRole[] = ["anon", "user", "admin"];
+const VALID_ACTIONS: PermissionAction[] = ["create", "read", "update", "delete"];
+
 /**
  * Validation error with context
  */
@@ -28,6 +31,8 @@ export const ValidationErrorCode = {
   DUPLICATE_TABLE: "DUPLICATE_TABLE",
   RESERVED_FIELD_NAME: "RESERVED_FIELD_NAME",
   SELF_REFERENCE_ON_REQUIRED: "SELF_REFERENCE_ON_REQUIRED",
+  INVALID_PERMISSION_ROLE: "INVALID_PERMISSION_ROLE",
+  INVALID_PERMISSION_ACTION: "INVALID_PERMISSION_ACTION",
 } as const;
 
 /**
@@ -113,6 +118,33 @@ export function validateSchema(schema: SchemaDefinition): ValidationError[] {
         });
       }
     }
+
+    // Validate $permissions if present
+    if (table.permissions) {
+      for (const [role, actions] of Object.entries(table.permissions)) {
+        if (!VALID_ROLES.includes(role as PermissionRole)) {
+          errors.push({
+            table: tableName,
+            field: "$permissions",
+            message: `Invalid permission role: "${role}". Valid roles: ${VALID_ROLES.join(", ")}`,
+            code: ValidationErrorCode.INVALID_PERMISSION_ROLE,
+          });
+        }
+
+        if (Array.isArray(actions)) {
+          for (const action of actions) {
+            if (!VALID_ACTIONS.includes(action as PermissionAction)) {
+              errors.push({
+                table: tableName,
+                field: "$permissions",
+                message: `Invalid permission action: "${action}". Valid actions: ${VALID_ACTIONS.join(", ")}`,
+                code: ValidationErrorCode.INVALID_PERMISSION_ACTION,
+              });
+            }
+          }
+        }
+      }
+    }
   }
 
   return errors;

package/src/types.ts

@@ -46,7 +46,7 @@ export interface FieldReference {
 }
 
 /**
- * Complete field definition after DSL processing
+ * Complete field definition (normalized from JSON schema)
  */
 export interface FieldDefinition {
   type: FieldType;
@@ -76,6 +76,25 @@ export interface FieldDefinition {
   match?: string; // RegExp pattern as string
 }
 
+// ==================== Permission Types ====================
+
+/**
+ * Permission roles for table access control
+ */
+export type PermissionRole = "anon" | "user" | "admin";
+
+/**
+ * Permission actions
+ */
+export type PermissionAction = "create" | "read" | "update" | "delete";
+
+/**
+ * Table-level permissions mapping roles to allowed actions.
+ * If not defined on a table, no restrictions apply (backward compatible).
+ * Enforced by the backend, not by the ORM.
+ */
+export type TablePermissions = Partial<Record<PermissionRole, PermissionAction[]>>;
+
 // ==================== Table & Schema Types ====================
 
 /**
@@ -84,6 +103,7 @@ export interface FieldDefinition {
 export interface TableDefinition {
   name: string;
   fields: Record<string, FieldDefinition>;
+  permissions?: TablePermissions;
 }
 
 /**
@@ -103,22 +123,6 @@ export interface SchemaDefinition {
   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) ====================
 
 /**

package/src/utils/jsonConverter.ts

@@ -5,7 +5,7 @@
  * Enables AI agents to work with JSON while maintaining type-safe internal representation.
  */
 
-import type {
+import type {
   JSONSchemaDefinition,
   JSONFieldDefinition,
   JSONFieldType,
@@ -13,23 +13,24 @@ import type {
   FieldDefinition,
   FieldType,
   TableDefinition,
-  LanguageConfig,
-} from "../types";
-
-const LANGUAGE_NAME_TO_CODE: Record<string, string> = {
-  english: "en",
-  turkish: "tr",
-  german: "de",
-  french: "fr",
-  spanish: "es",
-  russian: "ru",
-  arabic: "ar",
-};
-
-export interface ParseJSONSchemaResult {
-  schema: SchemaDefinition;
-  warnings: string[];
-}
+  LanguageConfig,
+  TablePermissions,
+} from "../types";
+
+const LANGUAGE_NAME_TO_CODE: Record<string, string> = {
+  english: "en",
+  turkish: "tr",
+  german: "de",
+  french: "fr",
+  spanish: "es",
+  russian: "ru",
+  arabic: "ar",
+};
+
+export interface ParseJSONSchemaResult {
+  schema: SchemaDefinition;
+  warnings: string[];
+}
 
 /**
  * Convert JSON schema to internal SchemaDefinition
@@ -52,119 +53,125 @@ export interface ParseJSONSchemaResult {
  * const schema = parseJSONSchema(jsonSchema);
  * ```
  */
-export function parseJSONSchema(json: JSONSchemaDefinition): SchemaDefinition {
-  return parseJSONSchemaWithWarnings(json).schema;
-}
-
-export function parseJSONSchemaWithWarnings(
-  json: JSONSchemaDefinition
-): ParseJSONSchemaResult {
-  const warnings: string[] = [];
-  const supported = (json.languages || ["en"]).map((lang) => normalizeLangToken(lang));
-  const defaultLanguage = resolveDefaultLanguage(
-    json.defaultLanguage,
-    supported,
-    warnings
-  );
-
-  const languages: LanguageConfig = {
-    default: defaultLanguage,
-    supported,
-  };
+export function parseJSONSchema(json: JSONSchemaDefinition): SchemaDefinition {
+  return parseJSONSchemaWithWarnings(json).schema;
+}
+
+export function parseJSONSchemaWithWarnings(
+  json: JSONSchemaDefinition
+): ParseJSONSchemaResult {
+  const warnings: string[] = [];
+  const supported = (json.languages || ["en"]).map((lang) => normalizeLangToken(lang));
+  const defaultLanguage = resolveDefaultLanguage(
+    json.defaultLanguage,
+    supported,
+    warnings
+  );
+
+  const languages: LanguageConfig = {
+    default: defaultLanguage,
+    supported,
+  };
 
   const tables: Record<string, TableDefinition> = {};
 
   for (const [tableName, jsonTable] of Object.entries(json.tables)) {
     const fields: Record<string, FieldDefinition> = {};
+    let permissions: TablePermissions | undefined;
 
     for (const [fieldName, jsonField] of Object.entries(jsonTable)) {
-      fields[fieldName] = convertJSONField(jsonField);
+      if (fieldName === "$permissions") {
+        permissions = jsonField as unknown as TablePermissions;
+        continue;
+      }
+      fields[fieldName] = convertJSONField(jsonField as JSONFieldDefinition);
     }
 
     tables[tableName] = {
       name: tableName,
       fields,
+      ...(permissions ? { permissions } : {}),
     };
   }
 
-  return {
-    schema: {
-      name: json.name,
-      languages,
-      tables,
-    },
-    warnings,
-  };
-}
-
-function normalizeLangToken(lang: string): string {
-  return String(lang).trim().toLowerCase();
-}
-
-function resolveDefaultLanguage(
-  input: string | undefined,
-  supported: string[],
-  warnings: string[]
-): string {
-  const fallback = supported[0] || "en";
-  if (!input) return fallback;
-
-  const normalizedInput = normalizeLangToken(input);
-  const directMatch = supported.find(
-    (lang) => normalizeLangToken(lang) === normalizedInput
-  );
-  if (directMatch) return directMatch;
-
-  const languageNameMatch = resolveLanguageNameToSupportedCode(
-    normalizedInput,
-    supported
-  );
-  if (languageNameMatch) {
-    warnings.push(
-      `Normalized defaultLanguage "${input}" to "${languageNameMatch}".`
-    );
-    return languageNameMatch;
-  }
-
-  throw new Error(
-    `Invalid defaultLanguage "${input}". Expected one of: ${supported.join(", ")}`
-  );
-}
-
-function resolveLanguageNameToSupportedCode(
-  normalizedInput: string,
-  supported: string[]
-): string | null {
-  const mapped = LANGUAGE_NAME_TO_CODE[normalizedInput];
-  if (mapped) {
-    const supportedMatch = supported.find(
-      (lang) => normalizeLangToken(lang) === mapped
-    );
-    if (supportedMatch) return supportedMatch;
-  }
-
-  for (const code of supported) {
-    const languageName = getLanguageDisplayName(code);
-    if (languageName && normalizeLangToken(languageName) === normalizedInput) {
-      return code;
-    }
-  }
-
-  return null;
-}
-
-function getLanguageDisplayName(code: string): string | null {
-  try {
-    if (typeof Intl === "undefined" || !("DisplayNames" in Intl)) {
-      return null;
-    }
-    const displayNames = new Intl.DisplayNames(["en"], { type: "language" });
-    const label = displayNames.of(code);
-    return label || null;
-  } catch {
-    return null;
-  }
-}
+  return {
+    schema: {
+      name: json.name,
+      languages,
+      tables,
+    },
+    warnings,
+  };
+}
+
+function normalizeLangToken(lang: string): string {
+  return String(lang).trim().toLowerCase();
+}
+
+function resolveDefaultLanguage(
+  input: string | undefined,
+  supported: string[],
+  warnings: string[]
+): string {
+  const fallback = supported[0] || "en";
+  if (!input) return fallback;
+
+  const normalizedInput = normalizeLangToken(input);
+  const directMatch = supported.find(
+    (lang) => normalizeLangToken(lang) === normalizedInput
+  );
+  if (directMatch) return directMatch;
+
+  const languageNameMatch = resolveLanguageNameToSupportedCode(
+    normalizedInput,
+    supported
+  );
+  if (languageNameMatch) {
+    warnings.push(
+      `Normalized defaultLanguage "${input}" to "${languageNameMatch}".`
+    );
+    return languageNameMatch;
+  }
+
+  throw new Error(
+    `Invalid defaultLanguage "${input}". Expected one of: ${supported.join(", ")}`
+  );
+}
+
+function resolveLanguageNameToSupportedCode(
+  normalizedInput: string,
+  supported: string[]
+): string | null {
+  const mapped = LANGUAGE_NAME_TO_CODE[normalizedInput];
+  if (mapped) {
+    const supportedMatch = supported.find(
+      (lang) => normalizeLangToken(lang) === mapped
+    );
+    if (supportedMatch) return supportedMatch;
+  }
+
+  for (const code of supported) {
+    const languageName = getLanguageDisplayName(code);
+    if (languageName && normalizeLangToken(languageName) === normalizedInput) {
+      return code;
+    }
+  }
+
+  return null;
+}
+
+function getLanguageDisplayName(code: string): string | null {
+  try {
+    if (typeof Intl === "undefined" || !("DisplayNames" in Intl)) {
+      return null;
+    }
+    const displayNames = new Intl.DisplayNames(["en"], { type: "language" });
+    const label = displayNames.of(code);
+    return label || null;
+  } catch {
+    return null;
+  }
+}
 
 /**
  * Normalize JSON-native type syntax to internal FieldType + properties
@@ -225,7 +232,7 @@ function convertJSONField(jsonField: JSONFieldDefinition): FieldDefinition {
     type,
     nullable: jsonField.nullable ?? !jsonField.required,
     unique: jsonField.unique ?? false,
-    primary: jsonField.primary ?? false,
+    primary: jsonField.primary ?? (type === "id"),
     default: jsonField.default,
     translatable: jsonField.translatable ?? false,
     properties,

package/src/utils/translationQuery.ts

@@ -44,21 +44,21 @@ function buildAliasedWhereClause(
 /**
  * Options for translation queries
  */
-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;
-}
+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
@@ -78,13 +78,13 @@ export function buildTranslationQuery(
     table,
     schema,
     lang,
-    fallbackLang = schema.languages.default,
-    mainFallbackFields,
-    where,
-    orderBy,
-    limit,
-    offset,
-  } = options;
+    fallbackLang = schema.languages.default,
+    mainFallbackFields,
+    where,
+    orderBy,
+    limit,
+    offset,
+  } = options;
 
   const tableSchema = schema.tables[table];
   if (!tableSchema) {
@@ -100,32 +100,32 @@ export function buildTranslationQuery(
   const transTable = toTranslationTableName(table);
   const fkName = toTranslationFKName(table);
 
-  const mainAlias = "m";
-  const transAlias = "t";
-  const fallbackAlias = "fb";
-  const mainFallbackSet =
-    mainFallbackFields !== undefined
-      ? new Set(mainFallbackFields)
-      : null;
+  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) {
-      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}`);
-    }
-  }
+  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}
@@ -170,24 +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,
-  mainFallbackFields?: string[]
-): TranslationQueryResult {
-  return buildTranslationQuery({
-    table,
-    schema,
-    lang,
-    fallbackLang,
-    mainFallbackFields,
-    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