webspresso 0.0.102 → 0.0.104

package/core/orm/scopes.js

@@ -6,6 +6,15 @@
 
 const { generateNanoid } = require('./utils/nanoid');
 
+/**
+ * Determine the soft delete column name for a model
+ * @param {import('./types').ModelDefinition} model - Model definition
+ * @returns {string} Column name ('deletedAt' or 'deleted_at')
+ */
+function getSoftDeleteColumn(model) {
+  return (model && model.columns && model.columns.has('deletedAt')) ? 'deletedAt' : 'deleted_at';
+}
+
 /**
  * Apply soft delete scope to a query builder
  * @param {import('knex').Knex.QueryBuilder} qb - Knex query builder
@@ -18,9 +27,11 @@ function applySoftDeleteScope(qb, context, model) {
     return qb;
   }
 
+  const deletedCol = getSoftDeleteColumn(model);
+
   // If onlyTrashed is set, only return deleted records
   if (context.onlyTrashed) {
-    return qb.whereNotNull('deleted_at');
+    return qb.whereNotNull(deletedCol);
   }
 
   // If withTrashed is set, return all records (no filter)
@@ -29,7 +40,7 @@ function applySoftDeleteScope(qb, context, model) {
   }
 
   // Default: only return non-deleted records
-  return qb.whereNull('deleted_at');
+  return qb.whereNull(deletedCol);
 }
 
 /**
@@ -74,10 +85,13 @@ function applyInsertTimestamps(data, model) {
   }
 
   const now = new Date();
+  const createdCol = (model.columns && model.columns.has('createdAt')) ? 'createdAt' : 'created_at';
+  const updatedCol = (model.columns && model.columns.has('updatedAt')) ? 'updatedAt' : 'updated_at';
+
   return {
     ...data,
-    created_at: data.created_at || now,
-    updated_at: data.updated_at || now,
+    [createdCol]: data[createdCol] !== undefined ? data[createdCol] : (data.createdAt || data.created_at || now),
+    [updatedCol]: data[updatedCol] !== undefined ? data[updatedCol] : (data.updatedAt || data.updated_at || now),
   };
 }
 
@@ -92,9 +106,11 @@ function applyUpdateTimestamps(data, model) {
     return data;
   }
 
+  const updatedCol = (model.columns && model.columns.has('updatedAt')) ? 'updatedAt' : 'updated_at';
+
   return {
     ...data,
-    updated_at: new Date(),
+    [updatedCol]: new Date(),
   };
 }
 
@@ -143,18 +159,32 @@ function applyInsertNanoidPrimary(data, model) {
 /**
  * Get soft delete data (for UPDATE instead of DELETE)
  * @param {Date|string|number} [date=new Date()] - Soft delete timestamp
+ * @param {string|import('./types').ModelDefinition} [colOrModel='deleted_at'] - Column name or model definition
  * @returns {Object} Soft delete update data
  */
-function getSoftDeleteData(date = new Date()) {
-  return { deleted_at: date instanceof Date ? date : new Date(date) };
+function getSoftDeleteData(date = new Date(), colOrModel = 'deleted_at') {
+  let columnName = 'deleted_at';
+  if (typeof colOrModel === 'string') {
+    columnName = colOrModel;
+  } else if (colOrModel && typeof colOrModel === 'object') {
+    columnName = getSoftDeleteColumn(colOrModel);
+  }
+  return { [columnName]: date instanceof Date ? date : new Date(date) };
 }
 
 /**
  * Get restore data (to undo soft delete)
+ * @param {string|import('./types').ModelDefinition} [colOrModel='deleted_at'] - Column name or model definition
  * @returns {Object} Restore update data
  */
-function getRestoreData() {
-  return { deleted_at: null };
+function getRestoreData(colOrModel = 'deleted_at') {
+  let columnName = 'deleted_at';
+  if (typeof colOrModel === 'string') {
+    columnName = colOrModel;
+  } else if (colOrModel && typeof colOrModel === 'object') {
+    columnName = getSoftDeleteColumn(colOrModel);
+  }
+  return { [columnName]: null };
 }
 
 /**
@@ -207,6 +237,7 @@ module.exports = {
   applyUpdateModifiers,
   getSoftDeleteData,
   getRestoreData,
+  getSoftDeleteColumn,
   createScopeContext,
 };
 

package/core/orm/types.js

@@ -150,12 +150,23 @@
 // Model Types
 // ============================================================================
 
+/**
+ * @typedef {Object} ModelConfigOptions
+ * @property {boolean|{createdAt?: string, updatedAt?: string, snakeCase?: boolean}} [timestamps=false] - Auto timestamps
+ * @property {boolean|{deletedAt?: string, snakeCase?: boolean}} [softDelete=false] - Soft delete support
+ * @property {boolean|{deletedAt?: string, snakeCase?: boolean}} [softDeletes=false] - Soft delete support alias
+ */
+
 /**
  * @typedef {Object} ModelOptions
  * @property {string} name - Model name (e.g., 'User')
  * @property {string} table - Database table name (e.g., 'users')
- * @property {import('zod').ZodObject} schema - Zod schema for validation
+ * @property {import('zod').ZodObject|Record<string, any>} schema - Zod schema or plain object schema shape
  * @property {string} [primaryKey='id'] - Primary key column name
+ * @property {boolean|{createdAt?: string, updatedAt?: string, snakeCase?: boolean}} [timestamps] - Auto timestamps (injects createdAt/updatedAt)
+ * @property {boolean|{deletedAt?: string, snakeCase?: boolean}} [softDelete] - Soft delete support (injects deletedAt)
+ * @property {boolean|{deletedAt?: string, snakeCase?: boolean}} [softDeletes] - Soft delete support alias
+ * @property {ModelConfigOptions} [options] - Additional model options (e.g. timestamps, softDelete)
  * @property {RelationsMap} [relations={}] - Relation definitions
  * @property {ScopeOptions} [scopes={}] - Scope options
  * @property {AdminMetadata} [admin] - Admin panel metadata

package/core/queue/manager.js

@@ -527,6 +527,11 @@ class QueueManager extends EventEmitter {
       }
     } catch (err) {
       this.emit('error', err);
+      // Back off polling interval on database or adapter error to avoid tight spin-loop
+      this._currentPollInterval = Math.min(
+        this.maxPollInterval,
+        Math.round(this._currentPollInterval * 2)
+      );
       this._scheduleNextTick(this._currentPollInterval);
       return;
     }

package/core/shutdown/shutdown-manager.js

@@ -206,7 +206,21 @@ class ShutdownManager {
 
       this._log('info', `Starting ${modeLabel} shutdown (reason: ${reason})`);
 
-      // 1. Close HTTP server adapters
+      // 1. Run plugin disposers in reverse registration order (terminates SSE streams, WebSockets, devReload clients, and workers)
+      if (this._disposers.length > 0) {
+        this._log('info', `Disposing ${this._disposers.length} plugins`);
+        // Reverse array to tear down dependencies in reverse order
+        const reverseDisposers = this._disposers.slice().reverse();
+        for (const { name, fn } of reverseDisposers) {
+          try {
+            await fn();
+          } catch (err) {
+            this._log('error', `Error in plugin disposer "${name}":`, err);
+          }
+        }
+      }
+
+      // 2. Close HTTP server adapters (gracefully drain in-flight HTTP requests)
       if (this._adapters.length > 0) {
         this._log('info', 'Closing HTTP server');
 
@@ -270,7 +284,7 @@ class ShutdownManager {
         }
       }
 
-      // 2. Run application shutdown hooks (app.onShutdown)
+      // 3. Run application shutdown hooks (app.onShutdown)
       if (this._hooks.length > 0) {
         this._log('info', `Running ${this._hooks.length} shutdown hooks`);
         for (const hook of this._hooks) {
@@ -282,20 +296,6 @@ class ShutdownManager {
         }
       }
 
-      // 3. Run plugin disposers in reverse registration order
-      if (this._disposers.length > 0) {
-        this._log('info', `Disposing ${this._disposers.length} plugins`);
-        // Reverse array to tear down dependencies in reverse order
-        const reverseDisposers = this._disposers.slice().reverse();
-        for (const { name, fn } of reverseDisposers) {
-          try {
-            await fn();
-          } catch (err) {
-            this._log('error', `Error in plugin disposer "${name}":`, err);
-          }
-        }
-      }
-
       // 4. Detach signal hooks from process
       this.disableShutdownHooks();
 

package/core/utils/crypto.js

@@ -0,0 +1,73 @@
+/**
+ * Webspresso Zero-Dependency Crypto & Security Utilities
+ *
+ * Lightweight, timing-attack resistant cryptographic helpers.
+ *
+ * @module core/utils/crypto
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Constant-time equality comparison to prevent timing attacks.
+ *
+ * Compares two strings or Buffers in constant time using `crypto.timingSafeEqual`.
+ * Handles length mismatches by executing a dummy comparison against identical buffer
+ * to protect against timing leakage while safely returning `false`.
+ *
+ * @param {string|Buffer} a - First value to compare
+ * @param {string|Buffer} b - Second value to compare
+ * @returns {boolean} True if values are identical, false otherwise
+ */
+function safeCompare(a, b) {
+  if (a === null || a === undefined || b === null || b === undefined) {
+    return false;
+  }
+
+  const isABuf = Buffer.isBuffer(a);
+  const isBBuf = Buffer.isBuffer(b);
+
+  if (isABuf && isBBuf) {
+    if (a.length !== b.length) {
+      if (a.length > 0) {
+        try {
+          crypto.timingSafeEqual(a, a);
+        } catch (_) {}
+      }
+      return false;
+    }
+    try {
+      return crypto.timingSafeEqual(a, b);
+    } catch (_) {
+      return false;
+    }
+  }
+
+  if (typeof a !== 'string' || typeof b !== 'string') {
+    return false;
+  }
+
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+
+  if (bufA.length !== bufB.length) {
+    try {
+      // Dummy comparison to prevent timing leaks on length mismatches
+      crypto.timingSafeEqual(bufA, bufA);
+    } catch (_) {}
+    return false;
+  }
+
+  try {
+    return crypto.timingSafeEqual(bufA, bufB);
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = {
+  safeCompare,
+  timingSafeEqual: safeCompare,
+};

package/core/utils/escape-html.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const { escapeHtml, unescapeHtml } = require('./html');
+
+module.exports = escapeHtml;
+module.exports.escapeHtml = escapeHtml;
+module.exports.unescapeHtml = unescapeHtml;

package/core/utils/fetch.js

@@ -0,0 +1,120 @@
+/**
+ * Webspresso Zero-Dependency Fetch Utility
+ *
+ * Lightweight, production-grade wrapper around native `fetch` with built-in:
+ * - Configurable timeout with automatic AbortController
+ * - Seamless signal composition (external AbortSignal + timeout AbortSignal)
+ * - Timer unreferencing (`timer.unref()`) to prevent hanging Node.js event loop
+ * - Semantic error wrapping (ETIMEDOUT / TimeoutError)
+ * - JSON convenience helper (`fetchWithTimeout.json`)
+ *
+ * @module core/utils/fetch
+ */
+
+'use strict';
+
+/**
+ * Executes a fetch request with timeout and abort controller support.
+ *
+ * @param {string | URL | Request} url - Target URL or Request instance
+ * @param {RequestInit & { timeout?: number }} [options] - Standard RequestInit plus optional timeout (ms)
+ * @returns {Promise<Response>}
+ */
+async function fetchWithTimeout(url, options = {}) {
+  const { timeout = 10000, signal, ...fetchOptions } = options;
+
+  if (signal && signal.aborted) {
+    const reason = (signal.reason !== undefined && signal.reason !== null)
+      ? signal.reason
+      : new Error('This operation was aborted');
+    throw reason;
+  }
+
+  if (typeof AbortController === 'undefined') {
+    return fetch(url, { ...fetchOptions, signal });
+  }
+
+  const controller = new AbortController();
+  let timer = null;
+  let callerSignalListener = null;
+
+  if (typeof timeout === 'number' && timeout > 0) {
+    timer = setTimeout(() => {
+      const err = new Error(`Request timed out after ${timeout}ms`);
+      err.name = 'TimeoutError';
+      err.code = 'ETIMEDOUT';
+      controller.abort(err);
+    }, timeout);
+    if (timer && typeof timer.unref === 'function') {
+      timer.unref();
+    }
+  }
+
+  if (signal) {
+    callerSignalListener = () => {
+      controller.abort(signal.reason);
+    };
+    signal.addEventListener('abort', callerSignalListener, { once: true });
+  }
+
+  try {
+    return await fetch(url, {
+      ...fetchOptions,
+      signal: controller.signal,
+    });
+  } catch (err) {
+    if (controller.signal.aborted && controller.signal.reason) {
+      const reason = controller.signal.reason;
+      if (reason instanceof Error && (reason.name === 'TimeoutError' || reason.code === 'ETIMEDOUT')) {
+        throw reason;
+      }
+    }
+    if (err && err.name === 'AbortError' && controller.signal.aborted && controller.signal.reason) {
+      throw controller.signal.reason;
+    }
+    throw err;
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    if (signal && callerSignalListener) {
+      signal.removeEventListener('abort', callerSignalListener);
+    }
+  }
+}
+
+/**
+ * Fetch with timeout and automatically parse JSON response.
+ *
+ * @param {string | URL | Request} url
+ * @param {RequestInit & { timeout?: number }} [options]
+ * @returns {Promise<{ res: Response, data: any }>}
+ */
+fetchWithTimeout.json = async function fetchJson(url, options = {}) {
+  const res = await fetchWithTimeout(url, {
+    ...options,
+    headers: {
+      Accept: 'application/json',
+      ...(options.headers || {}),
+    },
+  });
+  let data = null;
+  const contentType = (res.headers && typeof res.headers.get === 'function')
+    ? (res.headers.get('content-type') || '')
+    : '';
+  if (contentType.includes('application/json')) {
+    data = await res.json();
+  } else {
+    const text = await res.text();
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = { raw: text };
+    }
+  }
+  return { res, data };
+};
+
+module.exports = {
+  fetchWithTimeout,
+};

package/core/utils/get-client-ip.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { getClientIp } = require('./ip');
+
+module.exports = getClientIp;
+module.exports.getClientIp = getClientIp;

package/core/utils/html.js

@@ -0,0 +1,72 @@
+/**
+ * Webspresso Zero-Dependency HTML Utilities
+ *
+ * High-performance, XSS-safe HTML entity escaping and unescaping.
+ *
+ * @module core/utils/html
+ */
+
+'use strict';
+
+const HTML_ESCAPE_TEST_RE = /[&<>"']/;
+const HTML_ESCAPE_RE = /[&<>"']/g;
+
+const HTML_ESCAPES = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+const HTML_UNESCAPE_RE = /&(?:amp|lt|gt|quot|#39|#039|#x27);/g;
+
+const HTML_UNESCAPES = {
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&#039;': "'",
+  '&#x27;': "'",
+};
+
+/**
+ * Escapes characters with special meaning in HTML to prevent XSS injection attacks.
+ * Fast-paths strings without special characters to avoid unnecessary allocations.
+ *
+ * @param {unknown} value - Value to escape (converted to string; null/undefined becomes '')
+ * @returns {string} HTML-escaped string
+ */
+function escapeHtml(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  const str = typeof value === 'string' ? value : String(value);
+  if (!HTML_ESCAPE_TEST_RE.test(str)) {
+    return str;
+  }
+
+  return str.replace(HTML_ESCAPE_RE, (char) => HTML_ESCAPES[char]);
+}
+
+/**
+ * Unescapes common HTML entities back to their literal character representations.
+ *
+ * @param {unknown} value - HTML string to unescape
+ * @returns {string} Unescaped string
+ */
+function unescapeHtml(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  const str = typeof value === 'string' ? value : String(value);
+  return str.replace(HTML_UNESCAPE_RE, (match) => HTML_UNESCAPES[match] || match);
+}
+
+module.exports = {
+  escapeHtml,
+  unescapeHtml,
+};

package/core/utils/ip.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Universal Client IP Extraction Utility
+ * Safely extracts client IP address with proxy support, header normalizations,
+ * and customizable fallbacks.
+ *
+ * Precedence:
+ * 1. x-forwarded-for header (first IP if comma-separated or array)
+ * 2. x-real-ip header
+ * 3. req.ip (Express trust proxy / custom assignment)
+ * 4. req.connection.remoteAddress
+ * 5. req.socket.remoteAddress
+ * 6. req.info.remoteAddress (Fastify/Hapi compatibility)
+ * 7. fallback (defaults to '127.0.0.1' if not explicitly provided)
+ *
+ * @param {Object} [req] - Express / Node.js HTTP request object
+ * @param {any} [fallback='127.0.0.1'] - Fallback value if no IP could be extracted
+ * @returns {any}
+ */
+function getClientIp(req, fallback) {
+  const defaultFallback = arguments.length > 1 ? fallback : '127.0.0.1';
+  if (!req || typeof req !== 'object') {
+    return defaultFallback;
+  }
+
+  const headers = req.headers;
+
+  // 1. x-forwarded-for (can be string or array in Node HTTP/proxies)
+  let forwarded = headers ? (headers['x-forwarded-for'] || headers['X-Forwarded-For']) : undefined;
+  if (!forwarded && typeof req.get === 'function') {
+    forwarded = req.get('x-forwarded-for');
+  }
+
+  if (forwarded) {
+    const ips = typeof forwarded === 'string' ? forwarded.split(',') : forwarded;
+    const first = Array.isArray(ips) ? ips[0] : ips;
+    if (first && typeof first === 'string') {
+      const trimmed = first.trim();
+      if (trimmed) return trimmed;
+    }
+  }
+
+  // 2. x-real-ip
+  let realIp = headers ? (headers['x-real-ip'] || headers['X-Real-IP']) : undefined;
+  if (!realIp && typeof req.get === 'function') {
+    realIp = req.get('x-real-ip');
+  }
+  if (realIp && typeof realIp === 'string') {
+    const trimmed = realIp.trim();
+    if (trimmed) return trimmed;
+  }
+
+  // 3. req.ip
+  if (req.ip && typeof req.ip === 'string') {
+    const trimmed = req.ip.trim();
+    if (trimmed) return trimmed;
+  }
+
+  // 4. req.connection.remoteAddress
+  const connAddr = req.connection && req.connection.remoteAddress;
+  if (connAddr && typeof connAddr === 'string') {
+    const trimmed = connAddr.trim();
+    if (trimmed) return trimmed;
+  }
+
+  // 5. req.socket.remoteAddress
+  const sockAddr = req.socket && req.socket.remoteAddress;
+  if (sockAddr && typeof sockAddr === 'string') {
+    const trimmed = sockAddr.trim();
+    if (trimmed) return trimmed;
+  }
+
+  // 6. req.info.remoteAddress (Fastify/Hapi compatibility)
+  const infoAddr = req.info && req.info.remoteAddress;
+  if (infoAddr && typeof infoAddr === 'string') {
+    const trimmed = infoAddr.trim();
+    if (trimmed) return trimmed;
+  }
+
+  return defaultFallback;
+}
+
+module.exports = {
+  getClientIp,
+};

package/core/utils/safe-compare.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./crypto');

package/core/validation/index.js

@@ -22,13 +22,19 @@ function hasDangerousKeys(obj) {
     return false;
   }
   if (Array.isArray(obj)) {
-    return obj.some(item => hasDangerousKeys(item));
+    const len = obj.length;
+    for (let i = 0; i < len; i++) {
+      if (hasDangerousKeys(obj[i])) return true;
+    }
+    return false;
   }
-  for (const key of Object.keys(obj)) {
+  for (const key in obj) {
+    if (!Object.prototype.hasOwnProperty.call(obj, key)) continue;
     if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
       return true;
     }
-    if (typeof obj[key] === 'object' && obj[key] !== null && hasDangerousKeys(obj[key])) {
+    const val = obj[key];
+    if (val !== null && typeof val === 'object' && hasDangerousKeys(val)) {
       return true;
     }
   }

package/index.d.ts

@@ -830,6 +830,16 @@ export function loadListeners(dirPath: string, dispatcher: EventDispatcher, opti
 
 export function createHelpers(context: Record<string, unknown>): Record<string, unknown>;
 
+export interface FetchWithTimeoutOptions extends RequestInit {
+  timeout?: number;
+}
+
+export function fetchWithTimeout(url: string | URL | Request, options?: FetchWithTimeoutOptions): Promise<Response>;
+export function safeCompare(a: string | Buffer | null | undefined, b: string | Buffer | null | undefined): boolean;
+export function escapeHtml(value: unknown): string;
+export function unescapeHtml(value: unknown): string;
+export function getClientIp<T = string>(req?: any, fallback?: T): string | T;
+
 export const utils: Record<string, unknown>;
 
 export class AssetManager {
@@ -1072,11 +1082,20 @@ export type InferModel<T> = T extends ModelDefinition<infer TModel>
 export type InferModelCreate<T> = Partial<InferModel<T>> & Record<string, any>;
 export type InferModelUpdate<T> = Partial<InferModel<T>>;
 
-export interface ModelOptions<TSchema extends ZodObject<any> = ZodObject<Record<string, ZodTypeAny>>> {
+export interface ModelOptions<TSchema = ZodObject<Record<string, ZodTypeAny>>> {
   name: string;
   table: string;
-  schema: TSchema;
+  schema: TSchema | Record<string, any>;
   primaryKey?: string;
+  timestamps?: boolean | { createdAt?: string; updatedAt?: string; snakeCase?: boolean };
+  softDelete?: boolean | { deletedAt?: string; snakeCase?: boolean };
+  softDeletes?: boolean | { deletedAt?: string; snakeCase?: boolean };
+  options?: {
+    timestamps?: boolean | { createdAt?: string; updatedAt?: string; snakeCase?: boolean };
+    softDelete?: boolean | { deletedAt?: string; snakeCase?: boolean };
+    softDeletes?: boolean | { deletedAt?: string; snakeCase?: boolean };
+    [key: string]: unknown;
+  };
   relations?: Record<string, RelationDefinition>;
   scopes?: ScopeOptions;
   admin?: AdminMetadata;
@@ -1104,6 +1123,11 @@ export interface ModelDefinition<TModel = Record<string, any>> {
     timestamps: boolean;
     tenant: string | null;
   };
+  options?: {
+    timestamps?: boolean | { createdAt?: string; updatedAt?: string; snakeCase?: boolean };
+    softDelete?: boolean | { deletedAt?: string; snakeCase?: boolean };
+    [key: string]: unknown;
+  };
   columns: Map<string, unknown>;
   admin: {
     enabled: boolean;
@@ -1129,9 +1153,9 @@ export interface ModelDefinition<TModel = Record<string, any>> {
   cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
 
-export function defineModel<TSchema extends ZodObject<any>>(
+export function defineModel<TSchema = ZodObject<any>>(
   options: ModelOptions<TSchema>
-): ModelDefinition<import('zod').z.infer<TSchema>>;
+): ModelDefinition<any>;
 
 export function getModel<T = Record<string, any>>(name: string): ModelDefinition<T> | undefined;
 
@@ -1147,7 +1171,10 @@ export function isCascadeEnabled(relation: RelationDefinition, operation: 'delet
 
 /** zdb column helpers (id, string, timestamp, …) + `schema()` */
 export type Zdb = Record<string, any> & {
-  schema(shape: Record<string, ZodTypeAny>): ZodObject<Record<string, ZodTypeAny>>;
+  schema(shape: Record<string, any>): ZodObject<Record<string, ZodTypeAny>>;
+  timestamps(options?: { snakeCase?: boolean; createdAt?: string; updatedAt?: string }): Record<string, any>;
+  softDelete(options?: Record<string, any>): any;
+  softDeletes(options?: { snakeCase?: boolean; deletedAt?: string }): Record<string, any>;
 };
 
 export const zdb: Zdb;
@@ -3770,7 +3797,7 @@ export class SessionManager {
 }
 
 export function parseUserAgent(userAgent?: string): DeviceInfo;
-export function getClientIp(req?: any): string;
+export function getClientIp<T = string>(req?: any, fallback?: T): string | T;
 export function createUserSessionsTable(knex: any): Promise<void>;
 export function dropUserSessionsTable(knex: any): Promise<void>;
 export function createKnexSessionTracker(db: any, options?: { tableName?: string }): SessionTracker;