@promakeai/orm 1.0.6 → 1.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @promakeai/orm
 
-Core ORM package with schema DSL, query builder, and multi-language support. Platform-agnostic - works in both browser and Node.js.
+Core ORM package with query builder, schema validation, and multi-language support. Platform-agnostic - works in both browser and Node.js.
 
 ## Installation
 
@@ -8,144 +8,78 @@ Core ORM package with schema DSL, query builder, and multi-language support. Pla
 npm install @promakeai/orm
 ```
 
-## Schema Definition
-
-```typescript
-import { defineSchema, f } from '@promakeai/orm';
-
-const schema = defineSchema({
-  name: 'myapp',
-  languages: ['en', 'tr', 'de'],
-  tables: {
-    users: {
-      id: f.id(),
-      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().min(0),
-      stock: f.int().default(0),
-      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().required(),
-      parentId: f.int().ref({
-        table: 'categories',
-        onDelete: 'SET_NULL',
-      }),
-    },
-  },
-});
-```
-
-## 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
-
-### Constraints
-
-```typescript
-f.string()
-  .required()              // NOT NULL
-  .nullable()              // Allow NULL (default)
-  .unique()                // UNIQUE constraint
-  .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
-  .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')
+## JSON Schema (AI-Friendly)
+
+The JSON schema format is the runtime-friendly version and supports native
+arrays, typed objects, and role-based `$permissions`:
+
+```json
+{
+  "name": "myapp",
+  "languages": ["en", "tr"],
+  "defaultLanguage": "en",
+  "tables": {
+    "products": {
+      "$permissions": {
+        "anon": ["read"],
+        "user": ["read"],
+        "admin": ["read", "create", "update", "delete"]
+      },
+      "id": { "type": "id" },
+      "tags": { "type": ["string"] },
+      "metadata": { "type": { "color": "string", "weight": "number" } },
+      "variants": { "type": [{ "sku": "string", "price": "number" }] }
+    }
+  }
+}
 ```
 
-### Multi-Language
-
-```typescript
-f.string().translatable()  // Stored in {table}_translations
-f.text().translatable()
+## Field Types
+
+| Type | SQL | Description |
+|------|-----|-------------|
+| `"id"` | INTEGER PRIMARY KEY AUTOINCREMENT | Auto-increment primary key |
+| `"string"` | VARCHAR | Short text |
+| `"text"` | TEXT | Long text |
+| `"int"` | INTEGER | Integer |
+| `"decimal"` | REAL/DECIMAL | Decimal number |
+| `"bool"` | INTEGER (0/1) | Boolean |
+| `"timestamp"` | TEXT (ISO) | ISO datetime string |
+| `"json"` | TEXT | JSON serialized data |
+
+JSON schema type syntax supports `["string"]`, `["number"]`, `["boolean"]`, `{ "key": "string" }`,
+and `[{ "key": "string" }]` which are stored as JSON in SQL (TEXT) and typed in TS.
+
+## Field Modifiers (JSON)
+
+```json
+{
+  "email": {
+    "type": "string",
+    "required": true,
+    "unique": true,
+    "lowercase": true,
+    "trim": true,
+    "minLength": 1,
+    "maxLength": 255,
+    "enum": ["a", "b", "c"],
+    "match": "^[a-z]+$",
+    "default": "value"
+  },
+  "age": {
+    "type": "int",
+    "min": 0,
+    "max": 150
+  },
+  "categoryId": {
+    "type": "int",
+    "ref": "categories"
+  },
+  "name": {
+    "type": "string",
+    "translatable": true
+  }
+}
 ```
 
 ## Query Builder (MongoDB-style)
@@ -172,14 +106,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
-
-// JSON array contains
-buildWhereClause({ tags: { $contains: "sale" } });    // json_each(...) = "sale"
-buildWhereClause({ tags: { $containsAny: ["sale", "new"] } }); // json_each(...) IN (...)
+// 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({
@@ -225,23 +159,19 @@ buildWhereClause({
 
 ### Schema Configuration
 
-```typescript
-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
-    },
-  },
-});
+```json
+{
+  "languages": ["en", "tr", "de"],
+  "defaultLanguage": "en",
+  "tables": {
+    "products": {
+      "id": { "type": "id" },
+      "price": { "type": "decimal" },
+      "name": { "type": "string", "translatable": true },
+      "description": { "type": "text", "translatable": true }
+    }
+  }
+}
 ```
 
 ### Generated Tables
@@ -290,12 +220,12 @@ const { sql, params } = buildTranslationQuery('products', schema, {
 // LIMIT 10
 ```
 
-## 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.
+## 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';
@@ -335,6 +265,56 @@ const postsWithTags = await resolvePopulate(
 );
 ```
 
+## Permissions (`$permissions`)
+
+Role-based access control defined as table metadata in the JSON schema:
+
+```json
+"$permissions": {
+  "anon": ["read"],
+  "user": ["read", "create"],
+  "admin": ["read", "create", "update", "delete"]
+}
+```
+
+- **Roles:** `anon`, `user`, `admin`
+- **Actions:** `create`, `read`, `update`, `delete`
+- Not a database column — stored as metadata on `TableDefinition.permissions`
+
+```typescript
+import { getTablePermissions } from '@promakeai/orm';
+import type { PermissionRole, PermissionAction, TablePermissions } from '@promakeai/orm';
+
+const permissions = getTablePermissions(schema.tables.products);
+// { anon: ['read'], user: ['read'], admin: ['read', 'create', 'update', 'delete'] }
+```
+
+## REST Adapter
+
+REST API adapter with Bearer auth support. Works in both Node.js and browser.
+
+```typescript
+import { RestAdapter } from '@promakeai/orm';
+
+// Static token (server-side / CLI)
+const adapter = new RestAdapter({
+  baseUrl: 'https://api.example.com',
+  token: 'my-api-key',
+  schema,
+  defaultLang: 'en',
+});
+
+// Dynamic token callback (browser — called on every request)
+const adapter = new RestAdapter({
+  baseUrl: 'https://api.example.com',
+  getToken: () => localStorage.getItem('token'),
+  schema,
+  defaultLang: 'en',
+});
+```
+
+`getToken` takes priority over static `token` when both are provided.
+
 ## Schema Helpers
 
 ```typescript
@@ -347,6 +327,7 @@ import {
   isRequiredField,
   getMainTableFields,
   getTranslationTableFields,
+  getTablePermissions,
   toTranslationTableName,
   toTranslationFKName,
   singularize,
@@ -396,23 +377,6 @@ 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:
@@ -477,7 +441,13 @@ import type {
   PopulateOption,
   PaginatedResult,
   IDataAdapter,
+  PermissionRole,
+  PermissionAction,
+  TablePermissions,
 } from '@promakeai/orm';
+
+import { RestAdapter } from '@promakeai/orm';
+import type { RestAdapterConfig } from '@promakeai/orm';
 ```
 
 ## Related Packages

package/dist/adapters/RestAdapter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * REST API Adapter
+ *
+ * Communicates with a backend REST API implementing the /database endpoints.
+ * Works in both Node.js and browser environments (uses fetch).
+ */
+import type { IDataAdapter } from "./IDataAdapter";
+import type { QueryOptions, PaginatedResult, SchemaDefinition } from "../types";
+type FetchFn = (input: string, init?: any) => Promise<any>;
+export interface RestAdapterConfig {
+    /** Base URL for API (e.g., "https://backend.promake.ai/api") */
+    baseUrl: string;
+    /** Database endpoint prefix (default: "/database") */
+    databasePrefix?: string;
+    /** Static authorization token for Bearer auth */
+    token?: string;
+    /** Dynamic token getter - called on every request. Takes priority over static token. */
+    getToken?: () => string | null;
+    /** Custom headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Schema definition for translation support */
+    schema?: SchemaDefinition;
+    /** Default language for translations */
+    defaultLang?: string;
+    /** Custom fetch function (for testing/SSR) */
+    fetch?: FetchFn;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+export declare class RestAdapter implements IDataAdapter {
+    private baseUrl;
+    private databasePrefix;
+    private token?;
+    private getTokenFn?;
+    private customHeaders;
+    private fetchFn;
+    private timeout;
+    schema?: SchemaDefinition;
+    defaultLang?: string;
+    constructor(config: RestAdapterConfig);
+    private buildUrl;
+    private getHeaders;
+    private request;
+    private buildQueryParams;
+    private urlWithParams;
+    setSchema(schema: SchemaDefinition): void;
+    connect(): Promise<void>;
+    private mapFieldType;
+    close(): void;
+    list<T = unknown>(table: string, options?: QueryOptions): Promise<T[]>;
+    get<T = unknown>(table: string, id: string | number, options?: QueryOptions): Promise<T | null>;
+    findOne<T = unknown>(table: string, options?: QueryOptions): Promise<T | null>;
+    count(table: string, options?: QueryOptions): Promise<number>;
+    paginate<T = unknown>(table: string, page: number, limit: number, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    create<T = unknown>(table: string, data: Record<string, unknown>): Promise<T>;
+    update<T = unknown>(table: string, id: string | number, data: Record<string, unknown>, options?: {
+        translations?: Record<string, Record<string, unknown>>;
+    }): Promise<T>;
+    delete(table: string, id: string | number): Promise<boolean>;
+    createMany<T = unknown>(table: string, records: Record<string, unknown>[], options?: {
+        ignore?: boolean;
+        noAtomic?: boolean;
+    }): Promise<{
+        created: number;
+        ids: (number | bigint)[];
+    }>;
+    updateMany(table: string, updates: {
+        id: number | string;
+        data: Record<string, unknown>;
+    }[], options?: {
+        noAtomic?: boolean;
+    }): Promise<{
+        updated: number;
+    }>;
+    deleteMany(table: string, ids: (number | string)[], options?: {
+        noAtomic?: boolean;
+    }): Promise<{
+        deleted: number;
+    }>;
+    createWithTranslations<T = unknown>(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 = unknown>(table: string, id: string | number): Promise<T[]>;
+    raw<T = unknown>(query: string, params?: unknown[]): Promise<T[]>;
+    execute(query: string, params?: unknown[]): Promise<{
+        changes: number;
+        lastInsertRowid: number | bigint;
+    }>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    getTables(): Promise<string[]>;
+    getTableSchema(table: string): Promise<unknown[]>;
+}
+export {};

package/dist/index.d.ts

@@ -5,21 +5,21 @@
  *
  * @example
  * ```typescript
- * import { ORM, defineSchema, f } from '@promakeai/orm';
+ * import { ORM, parseJSONSchema } from '@promakeai/orm';
  *
- * // Define schema
- * const schema = defineSchema({
+ * // Parse JSON schema
+ * const schema = parseJSONSchema({
  *   languages: ['en', 'tr'],
  *   tables: {
  *     products: {
- *       id: f.id(),
- *       name: f.string().translatable().required(),
- *       price: f.decimal().required(),
- *       categoryId: f.int().ref('categories'),
+ *       id: { type: 'id' },
+ *       name: { type: 'string', translatable: true, required: true },
+ *       price: { type: 'decimal', required: true },
+ *       categoryId: { type: 'int', ref: 'categories' },
  *     },
  *     categories: {
- *       id: f.id(),
- *       name: f.string().translatable().required(),
+ *       id: { type: 'id' },
+ *       name: { type: 'string', translatable: true, required: true },
  *     },
  *   },
  * });
@@ -34,12 +34,11 @@
  */
 export { ORM } from "./ORM";
 export type { IDataAdapter } from "./adapters/IDataAdapter";
-export { defineSchema, f, mergeSchemas, createSchemaUnsafe, } from "./schema";
-export type { FieldBuilder } from "./schema";
+export { RestAdapter, type RestAdapterConfig } from "./adapters/RestAdapter";
 export { validateSchema, assertValidSchema, isValidSchema, validateTable, ValidationErrorCode, } from "./schema";
 export type { ValidationError } from "./schema";
 export { singularize, pluralize, toPascalCase, toCamelCase, toSnakeCase, toInterfaceName, toDbInterfaceName, toPascalCasePlural, toTranslationTableName, toTranslationFKName, } from "./schema";
-export { getTranslatableFields, getNonTranslatableFields, getInsertableFields, hasTranslatableFields, getPrimaryKeyField, getReferenceFields, getMainTableFields, getTranslationTableFields, isRequiredField, getRequiredFields, getRefTarget, getRefTargetFull, } from "./schema";
+export { getTranslatableFields, getNonTranslatableFields, getInsertableFields, hasTranslatableFields, getPrimaryKeyField, getReferenceFields, getMainTableFields, getTranslationTableFields, isRequiredField, getRequiredFields, getRefTarget, getRefTargetFull, getTablePermissions, } from "./schema";
 export { buildWhereClause } from "./utils/whereBuilder";
 export type { WhereResult } from "./utils/whereBuilder";
 export { buildTranslationQuery, buildTranslationQueryById, buildTranslationInsert, buildTranslationUpsert, extractTranslatableData, } from "./utils/translationQuery";
@@ -50,4 +49,4 @@ export { parseJSONSchema, parseJSONSchemaWithWarnings, } from "./utils/jsonConve
 export type { ParseJSONSchemaResult } from "./utils/jsonConverter";
 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";
+export type { FieldType, FieldDefinition, FieldReference, TableDefinition, LanguageConfig, SchemaDefinition, PermissionRole, PermissionAction, TablePermissions, JSONFieldType, JSONFieldDefinition, JSONTableDefinition, JSONSchemaDefinition, WhereCondition, OrderByOption, PopulateOption, PopulateNested, QueryOptions, PaginatedResult, ORMConfig, } from "./types";