webspresso 0.0.99 → 0.0.100

package/core/auth/user-agent.js

@@ -0,0 +1,161 @@
+/**
+ * Webspresso Zero-Dependency User-Agent & Device Parser
+ * Extracts browser, operating system, and device category from User-Agent header
+ * @module core/auth/user-agent
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} DeviceInfo
+ * @property {string} browser - Browser name with major version (e.g. 'Chrome 128', 'Safari 17')
+ * @property {string} os - Operating system name (e.g. 'macOS 14', 'Windows 11', 'iOS 17')
+ * @property {'desktop'|'mobile'|'tablet'|'bot'|'unknown'} device - Device category
+ * @property {boolean} isMobile
+ * @property {boolean} isTablet
+ * @property {boolean} isDesktop
+ * @property {boolean} isBot
+ */
+
+/**
+ * Extract client IP address handling proxies
+ * @param {Object} req - Express / Node.js HTTP request
+ * @returns {string}
+ */
+function getClientIp(req) {
+  if (!req) return '127.0.0.1';
+
+  const forwarded = req.headers?.['x-forwarded-for'];
+  if (forwarded) {
+    const ips = typeof forwarded === 'string' ? forwarded.split(',') : forwarded;
+    const first = Array.isArray(ips) ? ips[0] : ips;
+    if (first) return first.trim();
+  }
+
+  return req.headers?.['x-real-ip'] ||
+    req.ip ||
+    req.connection?.remoteAddress ||
+    req.socket?.remoteAddress ||
+    '127.0.0.1';
+}
+
+/**
+ * Parse raw User-Agent header string into structured device info
+ * Zero external dependencies — pure regex extraction
+ * 
+ * @param {string} [userAgent='']
+ * @returns {DeviceInfo}
+ */
+function parseUserAgent(userAgent = '') {
+  const ua = String(userAgent || '').trim();
+
+  if (!ua) {
+    return {
+      browser: 'Unknown',
+      os: 'Unknown',
+      device: 'unknown',
+      isMobile: false,
+      isTablet: false,
+      isDesktop: false,
+      isBot: false,
+    };
+  }
+
+  // 1. Detect Bots / Crawlers
+  const botPattern = /googlebot|bingbot|yandex|baiduspider|duckduckbot|slurp|twitterbot|facebookexternalhit|rogerbot|linkedinbot|embedly|quora link preview|showyoubot|outbrain|pinterest\/|slackbot|vkshare|w3c_validator|whatsapp|curl|wget|postman/i;
+  const isBot = botPattern.test(ua);
+
+  // 2. Detect Operating System
+  let os = 'Unknown';
+  if (/iPad/i.test(ua)) {
+    const match = ua.match(/OS ([\d_\.]+)/i);
+    os = match ? `iPadOS ${match[1].replace(/_/g, '.')}` : 'iPadOS';
+  } else if (/iPhone|iPod/i.test(ua)) {
+    const match = ua.match(/OS ([\d_\.]+)/i);
+    os = match ? `iOS ${match[1].replace(/_/g, '.')}` : 'iOS';
+  } else if (/Android/i.test(ua)) {
+    const match = ua.match(/Android (\d+(\.\d+)?)/i);
+    os = match ? `Android ${match[1]}` : 'Android';
+  } else if (/Macintosh|Mac OS X/i.test(ua)) {
+    const match = ua.match(/Mac OS X ([\d_\.]+)/i);
+    if (match) {
+      const ver = match[1].replace(/_/g, '.');
+      os = `macOS ${ver}`;
+    } else {
+      os = 'macOS';
+    }
+  } else if (/Windows/i.test(ua)) {
+    if (/Windows NT 10\.0/i.test(ua)) os = 'Windows 10/11';
+    else if (/Windows NT 6\.3/i.test(ua)) os = 'Windows 8.1';
+    else if (/Windows NT 6\.2/i.test(ua)) os = 'Windows 8';
+    else if (/Windows NT 6\.1/i.test(ua)) os = 'Windows 7';
+    else os = 'Windows';
+  } else if (/CrOS/i.test(ua)) {
+    os = 'ChromeOS';
+  } else if (/Linux/i.test(ua)) {
+    if (/Ubuntu/i.test(ua)) os = 'Ubuntu Linux';
+    else if (/Fedora/i.test(ua)) os = 'Fedora Linux';
+    else os = 'Linux';
+  }
+
+  // 3. Detect Browser
+  let browser = 'Unknown';
+  if (/Edg(e|A|iOS)?\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Edg(e|A|iOS)?\/(\d+)/i);
+    browser = `Edge ${match ? match[2] : ''}`.trim();
+  } else if (/OPR\/(\d+)/i.test(ua)) {
+    const match = ua.match(/OPR\/(\d+)/i);
+    browser = `Opera ${match ? match[1] : ''}`.trim();
+  } else if (/SamsungBrowser\/(\d+)/i.test(ua)) {
+    const match = ua.match(/SamsungBrowser\/(\d+)/i);
+    browser = `Samsung Internet ${match ? match[1] : ''}`.trim();
+  } else if (/Brave\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Brave\/(\d+)/i);
+    browser = `Brave ${match ? match[1] : ''}`.trim();
+  } else if (/Vivaldi\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Vivaldi\/(\d+)/i);
+    browser = `Vivaldi ${match ? match[1] : ''}`.trim();
+  } else if (/Chrome\/(\d+)/i.test(ua) && !/Chromium/i.test(ua)) {
+    const match = ua.match(/Chrome\/(\d+)/i);
+    browser = `Chrome ${match ? match[1] : ''}`.trim();
+  } else if (/Firefox\/(\d+)/i.test(ua) || /FxiOS\/(\d+)/i.test(ua)) {
+    const match = ua.match(/(?:Firefox|FxiOS)\/(\d+)/i);
+    browser = `Firefox ${match ? match[1] : ''}`.trim();
+  } else if (/Safari/i.test(ua) && /Version\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Version\/(\d+)/i);
+    browser = `Safari ${match ? match[1] : ''}`.trim();
+  } else if (/Safari/i.test(ua) && !/Chrome/i.test(ua)) {
+    browser = 'Safari';
+  } else if (/MSIE (\d+)/i.test(ua) || (/Trident/i.test(ua) && /rv:(\d+)/i.test(ua))) {
+    browser = 'Internet Explorer';
+  } else if (isBot) {
+    const botNameMatch = ua.match(/(googlebot|bingbot|duckduckbot|slurp|twitterbot|slackbot|curl|wget)/i);
+    browser = botNameMatch ? botNameMatch[1] : 'Bot';
+  }
+
+  // 4. Detect Device Category
+  const isTablet = /iPad|tablet/i.test(ua) || (/android/i.test(ua) && !/mobile/i.test(ua));
+  const isMobile = !isTablet && /mobile|iphone|ipod|android|blackberry|opera mini|windows phone/i.test(ua);
+  const isDesktop = !isTablet && !isMobile && !isBot;
+
+  let device = 'unknown';
+  if (isBot) device = 'bot';
+  else if (isTablet) device = 'tablet';
+  else if (isMobile) device = 'mobile';
+  else if (isDesktop) device = 'desktop';
+
+  return {
+    browser,
+    os,
+    device,
+    isMobile,
+    isTablet,
+    isDesktop,
+    isBot,
+  };
+}
+
+module.exports = {
+  getClientIp,
+  parseUserAgent,
+};

package/core/orm/index.js

@@ -7,7 +7,7 @@
 const path = require('path');
 const fs = require('fs');
 const { createSchemaHelpers, extractColumnsFromSchema, getColumnMeta } = require('./schema-helpers');
-const { defineModel, getModel, getAllModels, hasModel, clearRegistry, resolveModelName } = require('./model');
+const { defineModel, getModel, getAllModels, hasModel, clearRegistry, resolveModelName, isCascadeEnabled } = require('./model');
 const { createRepository } = require('./repository');
 const { createMigrationManager } = require('./migrations');
 const { createSeeder } = require('./seeder');
@@ -358,6 +358,7 @@ module.exports = {
   getAllModels,
   hasModel,
   clearRegistry,
+  isCascadeEnabled,
   // Column utilities
   extractColumnsFromSchema,
   getColumnMeta,

package/core/orm/model.js

@@ -83,7 +83,21 @@ function defineModel(options) {
       );
     }
 
-    normalizedRelations[relationName] = relation;
+    if (relation.cascade !== undefined && relation.cascade !== null) {
+      const validCascade = typeof relation.cascade === 'boolean' ||
+        typeof relation.cascade === 'string' ||
+        Array.isArray(relation.cascade) ||
+        (typeof relation.cascade === 'object' && relation.cascade !== null);
+      if (!validCascade) {
+        throw new Error(
+          `Invalid cascade option for relation "${relationName}" in model "${name}". Must be boolean, string, array, or object.`
+        );
+      }
+    }
+
+    normalizedRelations[relationName] = {
+      ...relation,
+    };
   }
 
   // Create model definition
@@ -277,6 +291,41 @@ function getRelationKeys(model, relationName) {
   };
 }
 
+/**
+ * Check if a relation has cascade enabled for a given operation ('delete' or 'restore')
+ * @param {import('./types').RelationDefinition} relation - Relation definition
+ * @param {'delete'|'restore'} operation - Operation to check
+ * @returns {boolean}
+ */
+function isCascadeEnabled(relation, operation) {
+  if (!relation || relation.cascade === undefined || relation.cascade === null) {
+    return false;
+  }
+  const { cascade } = relation;
+  if (cascade === true) {
+    return true;
+  }
+  if (cascade === false) {
+    return false;
+  }
+  const op = String(operation).toLowerCase();
+  if (typeof cascade === 'string') {
+    const c = cascade.toLowerCase();
+    return c === op || c === 'all';
+  }
+  if (Array.isArray(cascade)) {
+    return cascade.some(item => {
+      if (typeof item !== 'string') return false;
+      const c = item.toLowerCase();
+      return c === op || c === 'all';
+    });
+  }
+  if (typeof cascade === 'object' && cascade !== null) {
+    return Boolean(cascade[op]);
+  }
+  return false;
+}
+
 module.exports = {
   defineModel,
   getModel,
@@ -287,6 +336,7 @@ module.exports = {
   resolveModelName,
   resolveRelationModel,
   getRelationKeys,
+  isCascadeEnabled,
   // Export registry for testing
   _registry: modelRegistry,
 };

package/core/orm/repository.js

@@ -6,10 +6,12 @@
 
 const { createQueryBuilder } = require('./query-builder');
 const { loadRelations } = require('./eager-loader');
+const { resolveRelationModel, isCascadeEnabled } = require('./model');
 const {
   applyInsertModifiers,
   applyUpdateModifiers,
   getSoftDeleteData,
+  getRestoreData,
   createScopeContext,
   applyScopes,
 } = require('./scopes');
@@ -458,14 +460,236 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
   }
 
   /**
-   * Delete a record by primary key (soft delete if enabled)
+   * Cascade soft-delete child records for cascading relations
+   * @param {import('./types').ModelDefinition} currentModel
+   * @param {Object} record
+   * @param {Date} deletedAt
+   * @param {Object} [options={}]
+   * @param {Set<string>} [visited=new Set()]
+   */
+  async function cascadeSoftDelete(currentModel, record, deletedAt, options = {}, visited = new Set()) {
+    const pkVal = record[currentModel.primaryKey];
+    if (pkVal === undefined || pkVal === null) return;
+    const visitKey = `${currentModel.name}:${pkVal}`;
+    if (visited.has(visitKey)) return;
+    visited.add(visitKey);
+
+    const activeKnex = getActiveKnex();
+
+    for (const [relationName, relation] of Object.entries(currentModel.relations || {})) {
+      if (!['hasMany', 'hasOne'].includes(relation.type)) continue;
+      if (!isCascadeEnabled(relation, 'delete')) continue;
+
+      let relatedModel;
+      try {
+        relatedModel = resolveRelationModel(relation);
+      } catch {
+        continue;
+      }
+      if (!relatedModel || !relatedModel.scopes.softDelete) continue;
+
+      const localKey = relation.localKey || currentModel.primaryKey;
+      const foreignKey = relation.foreignKey;
+      const parentVal = record[localKey];
+      if (parentVal === undefined || parentVal === null) continue;
+
+      let childQuery = activeKnex(relatedModel.table)
+        .where(foreignKey, parentVal)
+        .whereNull('deleted_at');
+
+      if (scopeContext && scopeContext.tenantId !== undefined && relatedModel.scopes.tenant) {
+        childQuery = childQuery.where(relatedModel.scopes.tenant, scopeContext.tenantId);
+      }
+
+      const children = await childQuery.select('*');
+      if (!children || children.length === 0) continue;
+
+      const childIds = children.map(c => c[relatedModel.primaryKey]);
+
+      await activeKnex(relatedModel.table)
+        .whereIn(relatedModel.primaryKey, childIds)
+        .update(getSoftDeleteData(deletedAt));
+
+      if (cacheLayer) {
+        cacheLayer.invalidateModelAll(relatedModel);
+      }
+
+      const hasDeeper = Object.values(relatedModel.relations || {}).some(
+        r => ['hasMany', 'hasOne'].includes(r.type) && isCascadeEnabled(r, 'delete')
+      );
+      if (hasDeeper) {
+        for (const child of children) {
+          await cascadeSoftDelete(relatedModel, child, deletedAt, options, visited);
+        }
+      }
+
+      if (ModelEvents.hasListeners(relatedModel.name, Hooks.AFTER_DELETE)) {
+        for (const child of children) {
+          const childCtx = createEventContext(relatedModel.name, 'delete', getHookTrx());
+          ModelEvents.emit(relatedModel.name, Hooks.AFTER_DELETE, child, childCtx);
+        }
+      }
+    }
+  }
+
+  /**
+   * Cascade hard-delete child records for cascading relations
+   * @param {import('./types').ModelDefinition} currentModel
+   * @param {Object} record
+   * @param {Object} [options={}]
+   * @param {Set<string>} [visited=new Set()]
+   */
+  async function cascadeHardDelete(currentModel, record, options = {}, visited = new Set()) {
+    const pkVal = record[currentModel.primaryKey];
+    if (pkVal === undefined || pkVal === null) return;
+    const visitKey = `${currentModel.name}:${pkVal}`;
+    if (visited.has(visitKey)) return;
+    visited.add(visitKey);
+
+    const activeKnex = getActiveKnex();
+
+    for (const [relationName, relation] of Object.entries(currentModel.relations || {})) {
+      if (!['hasMany', 'hasOne'].includes(relation.type)) continue;
+      if (!isCascadeEnabled(relation, 'delete')) continue;
+
+      let relatedModel;
+      try {
+        relatedModel = resolveRelationModel(relation);
+      } catch {
+        continue;
+      }
+      if (!relatedModel) continue;
+
+      const localKey = relation.localKey || currentModel.primaryKey;
+      const foreignKey = relation.foreignKey;
+      const parentVal = record[localKey];
+      if (parentVal === undefined || parentVal === null) continue;
+
+      let childQuery = activeKnex(relatedModel.table)
+        .where(foreignKey, parentVal);
+
+      if (scopeContext && scopeContext.tenantId !== undefined && relatedModel.scopes.tenant) {
+        childQuery = childQuery.where(relatedModel.scopes.tenant, scopeContext.tenantId);
+      }
+
+      const children = await childQuery.select('*');
+      if (!children || children.length === 0) continue;
+
+      // Delete deeper relations first to avoid FK constraint violations
+      const hasDeeper = Object.values(relatedModel.relations || {}).some(
+        r => ['hasMany', 'hasOne'].includes(r.type) && isCascadeEnabled(r, 'delete')
+      );
+      if (hasDeeper) {
+        for (const child of children) {
+          await cascadeHardDelete(relatedModel, child, options, visited);
+        }
+      }
+
+      const childIds = children.map(c => c[relatedModel.primaryKey]);
+      await activeKnex(relatedModel.table)
+        .whereIn(relatedModel.primaryKey, childIds)
+        .delete();
+
+      if (cacheLayer) {
+        cacheLayer.invalidateModelAll(relatedModel);
+      }
+
+      if (ModelEvents.hasListeners(relatedModel.name, Hooks.AFTER_DELETE)) {
+        for (const child of children) {
+          const childCtx = createEventContext(relatedModel.name, 'delete', getHookTrx());
+          ModelEvents.emit(relatedModel.name, Hooks.AFTER_DELETE, child, childCtx);
+        }
+      }
+    }
+  }
+
+  /**
+   * Cascade restore child records for cascading relations
+   * @param {import('./types').ModelDefinition} currentModel
+   * @param {Object} trashedRecord
+   * @param {Date|string|number} parentDeletedAt
+   * @param {Object} [options={}]
+   * @param {Set<string>} [visited=new Set()]
+   */
+  async function cascadeRestore(currentModel, trashedRecord, parentDeletedAt, options = {}, visited = new Set()) {
+    const pkVal = trashedRecord[currentModel.primaryKey];
+    if (pkVal === undefined || pkVal === null) return;
+    const visitKey = `${currentModel.name}:${pkVal}`;
+    if (visited.has(visitKey)) return;
+    visited.add(visitKey);
+
+    const activeKnex = getActiveKnex();
+
+    for (const [relationName, relation] of Object.entries(currentModel.relations || {})) {
+      if (!['hasMany', 'hasOne'].includes(relation.type)) continue;
+      if (!isCascadeEnabled(relation, 'restore')) continue;
+
+      let relatedModel;
+      try {
+        relatedModel = resolveRelationModel(relation);
+      } catch {
+        continue;
+      }
+      if (!relatedModel || !relatedModel.scopes.softDelete) continue;
+
+      const localKey = relation.localKey || currentModel.primaryKey;
+      const foreignKey = relation.foreignKey;
+      const parentVal = trashedRecord[localKey];
+      if (parentVal === undefined || parentVal === null) continue;
+
+      let childQuery = activeKnex(relatedModel.table)
+        .where(foreignKey, parentVal)
+        .whereNotNull('deleted_at');
+
+      if (scopeContext && scopeContext.tenantId !== undefined && relatedModel.scopes.tenant) {
+        childQuery = childQuery.where(relatedModel.scopes.tenant, scopeContext.tenantId);
+      }
+
+      // Selective restore by matching deletion timestamp
+      if (!options.allChildren && parentDeletedAt != null) {
+        childQuery = childQuery.where('deleted_at', parentDeletedAt);
+      }
+
+      const children = await childQuery.select('*');
+      if (!children || children.length === 0) continue;
+
+      const hasDeeper = Object.values(relatedModel.relations || {}).some(
+        r => ['hasMany', 'hasOne'].includes(r.type) && isCascadeEnabled(r, 'restore')
+      );
+      if (hasDeeper) {
+        for (const child of children) {
+          await cascadeRestore(relatedModel, child, child.deleted_at || parentDeletedAt, options, visited);
+        }
+      }
+
+      const childIds = children.map(c => c[relatedModel.primaryKey]);
+      await activeKnex(relatedModel.table)
+        .whereIn(relatedModel.primaryKey, childIds)
+        .update(getRestoreData());
+
+      if (cacheLayer) {
+        cacheLayer.invalidateModelAll(relatedModel);
+      }
+
+      if (ModelEvents.hasListeners(relatedModel.name, Hooks.AFTER_RESTORE)) {
+        for (const child of children) {
+          const childCtx = createEventContext(relatedModel.name, 'restore', getHookTrx());
+          ModelEvents.emit(relatedModel.name, Hooks.AFTER_RESTORE, { ...child, deleted_at: null }, childCtx);
+        }
+      }
+    }
+  }
+
+  /**
+   * Delete a record by primary key (soft delete if enabled, with relation cascading)
    * @param {number|string} id - Primary key value
+   * @param {Object} [options={}] - Delete options ({ cascade?: boolean, deletedAt?: Date })
    * @returns {Promise<boolean>}
    */
-  async function del(id) {
+  async function del(id, options = {}) {
     const ctx = createEventContext(model.name, 'delete', getHookTrx());
     
-    // Get the record before deletion for hooks
+    // Get the record before deletion for hooks and cascading
     const record = await findById(id);
     if (!record) {
       return false;
@@ -478,39 +702,76 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     }
 
     let success = false;
+    const deletedAt = (options && options.deletedAt instanceof Date) ? options.deletedAt : new Date();
 
     // Soft delete if enabled
     if (model.scopes.softDelete) {
       const updated = await baseQuery()
         .where(model.primaryKey, id)
-        .update(getSoftDeleteData());
+        .update(getSoftDeleteData(deletedAt));
       success = updated > 0;
+
+      if (success) {
+        if (cacheLayer) {
+          cacheLayer.invalidateModelAll(model);
+        }
+
+        if (!options || options.cascade !== false) {
+          await cascadeSoftDelete(model, record, deletedAt, options);
+        }
+
+        // Emit afterDelete
+        ModelEvents.emit(model.name, Hooks.AFTER_DELETE, record, ctx);
+      }
     } else {
       // Hard delete
+      // Cascade hard-delete child records first to satisfy FK constraints
+      if (!options || options.cascade !== false) {
+        await cascadeHardDelete(model, record, options);
+      }
+
       const deleted = await baseQuery()
         .where(model.primaryKey, id)
         .delete();
       success = deleted > 0;
-    }
 
-    if (success) {
-      // Emit afterDelete
-      ModelEvents.emit(model.name, Hooks.AFTER_DELETE, record, ctx);
+      if (success) {
+        if (cacheLayer) {
+          cacheLayer.invalidateModelAll(model);
+        }
+
+        // Emit afterDelete
+        ModelEvents.emit(model.name, Hooks.AFTER_DELETE, record, ctx);
+      }
     }
 
     return success;
   }
 
   /**
-   * Force delete a record (bypass soft delete)
+   * Force delete a record (bypass soft delete, cascading to related models)
    * @param {number|string} id - Primary key value
+   * @param {Object} [options={}] - Force delete options ({ cascade?: boolean })
    * @returns {Promise<boolean>}
    */
-  async function forceDelete(id) {
+  async function forceDelete(id, options = {}) {
+    const record = await getActiveKnex()(model.table)
+      .where(model.primaryKey, id)
+      .first();
+
+    if (!record) {
+      return false;
+    }
+
+    if (!options || options.cascade !== false) {
+      await cascadeHardDelete(model, record, options);
+    }
+
     // Use raw query to bypass soft delete scope
     const deleted = await getActiveKnex()(model.table)
       .where(model.primaryKey, id)
       .delete();
+
     if (cacheLayer && deleted > 0) {
       cacheLayer.invalidateModelAll(model);
     }
@@ -518,11 +779,12 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
   }
 
   /**
-   * Restore a soft-deleted record
+   * Restore a soft-deleted record (with selective cascading restore)
    * @param {number|string} id - Primary key value
+   * @param {Object} [options={}] - Restore options ({ cascade?: boolean, allChildren?: boolean })
    * @returns {Promise<Object|null>}
    */
-  async function restore(id) {
+  async function restore(id, options = {}) {
     if (!model.scopes.softDelete) {
       throw new Error(`Model "${model.name}" does not have soft delete enabled`);
     }
@@ -549,12 +811,20 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     const updated = await getActiveKnex()(model.table)
       .where(model.primaryKey, id)
       .whereNotNull('deleted_at')
-      .update({ deleted_at: null });
+      .update(getRestoreData());
 
     if (updated === 0) {
       return null;
     }
 
+    if (cacheLayer) {
+      cacheLayer.invalidateModelAll(model);
+    }
+
+    if (!options || options.cascade !== false) {
+      await cascadeRestore(model, trashedRecord, trashedRecord.deleted_at, options);
+    }
+
     const record = await findById(id, {}, false);
 
     // Emit afterRestore

package/core/orm/scopes.js

@@ -142,10 +142,11 @@ function applyInsertNanoidPrimary(data, model) {
 
 /**
  * Get soft delete data (for UPDATE instead of DELETE)
+ * @param {Date|string|number} [date=new Date()] - Soft delete timestamp
  * @returns {Object} Soft delete update data
  */
-function getSoftDeleteData() {
-  return { deleted_at: new Date() };
+function getSoftDeleteData(date = new Date()) {
+  return { deleted_at: date instanceof Date ? date : new Date(date) };
 }
 
 /**

package/core/orm/types.js

@@ -79,12 +79,17 @@
  * @typedef {'belongsTo'|'hasMany'|'hasOne'} RelationType
  */
 
+/**
+ * @typedef {boolean|'delete'|'restore'|'all'|string[]|{delete?: boolean, restore?: boolean}} RelationCascadeOption
+ */
+
 /**
  * @typedef {Object} RelationDefinition
  * @property {RelationType} type - Type of relation
- * @property {() => ModelDefinition} model - Lazy reference to related model
+ * @property {string|(() => ModelDefinition|string)} model - Related model reference (function or model name)
  * @property {string} foreignKey - Foreign key column name
  * @property {string} [localKey='id'] - Local key column name (for hasMany/hasOne)
+ * @property {RelationCascadeOption} [cascade=false] - Cascading delete and restore configuration
  */
 
 /**