webspresso 0.0.5 → 0.0.7

package/core/orm/types.js

@@ -0,0 +1,237 @@
+/**
+ * Webspresso ORM - Type Definitions
+ * JSDoc types for IDE support and documentation
+ * @module core/orm/types
+ */
+
+// ============================================================================
+// Column Metadata Types
+// ============================================================================
+
+/**
+ * @typedef {'id'|'string'|'text'|'integer'|'bigint'|'float'|'decimal'|'boolean'|'date'|'datetime'|'timestamp'|'json'|'enum'|'uuid'} ColumnType
+ */
+
+/**
+ * @typedef {Object} ColumnMeta
+ * @property {ColumnType} type - Database column type
+ * @property {boolean} [nullable=false] - Whether column allows NULL
+ * @property {boolean} [primary=false] - Whether column is primary key
+ * @property {boolean} [autoIncrement=false] - Whether column auto-increments
+ * @property {boolean} [unique=false] - Whether column has unique constraint
+ * @property {boolean} [index=false] - Whether column should be indexed
+ * @property {*} [default] - Default value for column
+ * @property {number} [maxLength] - Maximum length for string columns
+ * @property {number} [precision] - Precision for decimal columns
+ * @property {number} [scale] - Scale for decimal columns
+ * @property {string[]} [enumValues] - Allowed values for enum columns
+ * @property {string} [references] - Referenced table for foreign keys
+ * @property {string} [referenceColumn='id'] - Referenced column name
+ * @property {'create'|'update'} [auto] - Auto-set on create or update (for timestamps)
+ */
+
+/**
+ * Encoded column metadata stored in Zod .describe()
+ * @typedef {Object} EncodedColumnMeta
+ * @property {string} __wdb__ - Marker to identify ORM metadata
+ * @property {ColumnMeta} meta - The actual column metadata
+ */
+
+// ============================================================================
+// Relation Types
+// ============================================================================
+
+/**
+ * @typedef {'belongsTo'|'hasMany'|'hasOne'} RelationType
+ */
+
+/**
+ * @typedef {Object} RelationDefinition
+ * @property {RelationType} type - Type of relation
+ * @property {() => ModelDefinition} model - Lazy reference to related model
+ * @property {string} foreignKey - Foreign key column name
+ * @property {string} [localKey='id'] - Local key column name (for hasMany/hasOne)
+ */
+
+/**
+ * @typedef {Object.<string, RelationDefinition>} RelationsMap
+ */
+
+// ============================================================================
+// Scope Types
+// ============================================================================
+
+/**
+ * @typedef {Object} ScopeOptions
+ * @property {boolean} [softDelete=false] - Enable soft delete (deleted_at column)
+ * @property {boolean} [timestamps=false] - Enable auto timestamps (created_at, updated_at)
+ * @property {string} [tenant] - Tenant column name for multi-tenancy
+ */
+
+/**
+ * @typedef {Object} ScopeContext
+ * @property {*} [tenantId] - Current tenant ID for multi-tenant queries
+ * @property {boolean} [withTrashed=false] - Include soft-deleted records
+ * @property {boolean} [onlyTrashed=false] - Only soft-deleted records
+ */
+
+// ============================================================================
+// Model Types
+// ============================================================================
+
+/**
+ * @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 {string} [primaryKey='id'] - Primary key column name
+ * @property {RelationsMap} [relations={}] - Relation definitions
+ * @property {ScopeOptions} [scopes={}] - Scope options
+ */
+
+/**
+ * @typedef {Object} ModelDefinition
+ * @property {string} name - Model name
+ * @property {string} table - Database table name
+ * @property {import('zod').ZodObject} schema - Zod schema
+ * @property {string} primaryKey - Primary key column name
+ * @property {RelationsMap} relations - Relation definitions
+ * @property {ScopeOptions} scopes - Scope options
+ * @property {Map<string, ColumnMeta>} columns - Parsed column metadata
+ */
+
+// ============================================================================
+// Query Builder Types
+// ============================================================================
+
+/**
+ * @typedef {'='|'!='|'>'|'>='|'<'|'<='|'like'|'ilike'|'in'|'not in'|'is null'|'is not null'} WhereOperator
+ */
+
+/**
+ * @typedef {Object} WhereClause
+ * @property {string} column - Column name
+ * @property {WhereOperator} operator - Comparison operator
+ * @property {*} value - Value to compare
+ * @property {'and'|'or'} [boolean='and'] - Boolean operator for chaining
+ */
+
+/**
+ * @typedef {Object} OrderByClause
+ * @property {string} column - Column name
+ * @property {'asc'|'desc'} [direction='asc'] - Sort direction
+ */
+
+/**
+ * @typedef {Object} QueryState
+ * @property {WhereClause[]} wheres - WHERE clauses
+ * @property {OrderByClause[]} orderBys - ORDER BY clauses
+ * @property {string[]} selects - SELECT columns
+ * @property {string[]} withs - Relations to eager load
+ * @property {number} [limitValue] - LIMIT value
+ * @property {number} [offsetValue] - OFFSET value
+ * @property {ScopeContext} scopeContext - Current scope context
+ */
+
+// ============================================================================
+// Repository Types
+// ============================================================================
+
+/**
+ * @typedef {Object} FindOptions
+ * @property {string[]} [with=[]] - Relations to eager load
+ * @property {string[]} [select] - Columns to select
+ */
+
+/**
+ * @typedef {Object} PaginationOptions
+ * @property {number} [page=1] - Page number (1-indexed)
+ * @property {number} [perPage=15] - Items per page
+ */
+
+/**
+ * @typedef {Object} PaginatedResult
+ * @property {Object[]} data - Result items
+ * @property {number} total - Total count
+ * @property {number} page - Current page
+ * @property {number} perPage - Items per page
+ * @property {number} totalPages - Total pages
+ */
+
+// ============================================================================
+// Migration Types
+// ============================================================================
+
+/**
+ * @typedef {Object} MigrationConfig
+ * @property {string} [directory='./migrations'] - Migrations directory
+ * @property {string} [tableName='knex_migrations'] - Migration tracking table
+ */
+
+/**
+ * @typedef {Object} MigrationStatus
+ * @property {string} name - Migration filename
+ * @property {boolean} completed - Whether migration has run
+ * @property {Date} [ran_at] - When migration was run
+ * @property {number} [batch] - Migration batch number
+ */
+
+/**
+ * @typedef {Object} MigrationResult
+ * @property {number} batch - Batch number
+ * @property {string[]} migrations - Migration names run
+ */
+
+// ============================================================================
+// Database Types
+// ============================================================================
+
+/**
+ * @typedef {Object} DatabaseConfig
+ * @property {string} client - Database client ('pg', 'mysql2', 'better-sqlite3')
+ * @property {string|Object} connection - Connection string or config object
+ * @property {MigrationConfig} [migrations] - Migration configuration
+ * @property {Object} [pool] - Connection pool settings
+ */
+
+/**
+ * @typedef {Object} DatabaseInstance
+ * @property {import('knex').Knex} knex - Knex instance
+ * @property {function(ModelDefinition): Repository} createRepository - Create repository for model
+ * @property {function(function(TransactionContext): Promise): Promise} transaction - Run in transaction
+ * @property {MigrationManager} migrate - Migration manager
+ * @property {function(): Promise<void>} destroy - Close all connections
+ */
+
+/**
+ * @typedef {Object} TransactionContext
+ * @property {import('knex').Knex.Transaction} trx - Knex transaction
+ * @property {function(ModelDefinition): Repository} createRepository - Create repository in transaction
+ */
+
+/**
+ * @typedef {Object} Repository
+ * @property {function(number|string, FindOptions=): Promise<Object|null>} findById - Find by primary key
+ * @property {function(Object, FindOptions=): Promise<Object|null>} findOne - Find single record
+ * @property {function(FindOptions=): Promise<Object[]>} findAll - Find all records
+ * @property {function(Object): Promise<Object>} create - Create new record
+ * @property {function(number|string, Object): Promise<Object|null>} update - Update record
+ * @property {function(number|string): Promise<boolean>} delete - Delete record (soft if enabled)
+ * @property {function(number|string): Promise<boolean>} forceDelete - Hard delete record
+ * @property {function(): QueryBuilder} query - Get query builder
+ */
+
+/**
+ * @typedef {Object} MigrationManager
+ * @property {function(): Promise<MigrationResult>} latest - Run pending migrations
+ * @property {function(Object=): Promise<MigrationResult>} rollback - Rollback migrations
+ * @property {function(): Promise<MigrationStatus[]>} status - Get migration status
+ * @property {function(string, Object=): Promise<string>} make - Create new migration file
+ */
+
+// ============================================================================
+// Exports (for type resolution)
+// ============================================================================
+
+module.exports = {};
+

package/core/orm/utils.js

@@ -0,0 +1,127 @@
+/**
+ * Webspresso ORM - Utilities
+ * Internal helper functions
+ * @module core/orm/utils
+ */
+
+/**
+ * Pick specific keys from an object
+ * @param {Object} obj - Source object
+ * @param {string[]} keys - Keys to pick
+ * @returns {Object}
+ */
+function pick(obj, keys) {
+  const result = {};
+  for (const key of keys) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Omit specific keys from an object
+ * @param {Object} obj - Source object
+ * @param {string[]} keys - Keys to omit
+ * @returns {Object}
+ */
+function omit(obj, keys) {
+  const result = {};
+  const omitSet = new Set(keys);
+  for (const key in obj) {
+    if (!omitSet.has(key)) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Format date for database
+ * @param {Date} date - Date to format
+ * @returns {string}
+ */
+function formatDateForDb(date) {
+  return date.toISOString();
+}
+
+/**
+ * Generate timestamp for migration filename
+ * @returns {string} Format: YYYYMMDD_HHmmss
+ */
+function generateMigrationTimestamp() {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  const hours = String(now.getHours()).padStart(2, '0');
+  const minutes = String(now.getMinutes()).padStart(2, '0');
+  const seconds = String(now.getSeconds()).padStart(2, '0');
+  
+  return `${year}${month}${day}_${hours}${minutes}${seconds}`;
+}
+
+/**
+ * Convert snake_case to camelCase
+ * @param {string} str - Snake case string
+ * @returns {string}
+ */
+function snakeToCamel(str) {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+/**
+ * Convert camelCase to snake_case
+ * @param {string} str - Camel case string
+ * @returns {string}
+ */
+function camelToSnake(str) {
+  return str.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);
+}
+
+/**
+ * Ensure a value is an array
+ * @param {*} value - Value to wrap
+ * @returns {Array}
+ */
+function ensureArray(value) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Deep clone an object (simple version, no circular refs)
+ * @param {Object} obj - Object to clone
+ * @returns {Object}
+ */
+function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  if (obj instanceof Date) {
+    return new Date(obj);
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(deepClone);
+  }
+  const cloned = {};
+  for (const key in obj) {
+    cloned[key] = deepClone(obj[key]);
+  }
+  return cloned;
+}
+
+module.exports = {
+  pick,
+  omit,
+  formatDateForDb,
+  generateMigrationTimestamp,
+  snakeToCamel,
+  camelToSnake,
+  ensureArray,
+  deepClone,
+};
+

package/index.js

@@ -26,6 +26,12 @@ const {
   resetPluginManager
 } = require('./src/plugin-manager');
 
+// ORM exports (lazy loaded)
+const orm = require('./core/orm');
+
+// Built-in plugins
+const { schemaExplorerPlugin } = require('./plugins');
+
 module.exports = {
   // Main API
   createApp,
@@ -52,6 +58,12 @@ module.exports = {
   PluginManager,
   createPluginManager,
   getPluginManager,
-  resetPluginManager
+  resetPluginManager,
+  
+  // ORM
+  ...orm,
+  
+  // Plugins
+  schemaExplorerPlugin,
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {
@@ -18,7 +18,9 @@
     "express",
     "file-based-routing",
     "i18n",
-    "framework"
+    "framework",
+    "orm",
+    "knex"
   ],
   "author": "cond",
   "license": "MIT",
@@ -29,25 +31,47 @@
   "files": [
     "index.js",
     "bin/",
-    "src/"
+    "src/",
+    "utils/",
+    "core/"
   ],
   "dependencies": {
     "commander": "^11.1.0",
     "express": "^4.18.2",
     "helmet": "^7.2.0",
     "inquirer": "^8.2.6",
-    "nunjucks": "^3.2.4"
+    "knex": "^3.1.0",
+    "nunjucks": "^3.2.4",
+    "zod": "^3.23.0"
   },
   "peerDependencies": {
-    "dotenv": "^16.0.0"
+    "dotenv": "^16.0.0",
+    "pg": "^8.0.0",
+    "mysql2": "^3.0.0",
+    "better-sqlite3": "^9.0.0",
+    "@faker-js/faker": "^9.0.0"
   },
   "peerDependenciesMeta": {
     "dotenv": {
       "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@faker-js/faker": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@faker-js/faker": "^9.3.0",
     "@vitest/coverage-v8": "^1.2.0",
+    "better-sqlite3": "^11.0.0",
     "chokidar": "^3.5.3",
     "dotenv": "^16.3.1",
     "release-it": "^17.11.0",

package/src/plugin-manager.js

@@ -449,3 +449,5 @@ module.exports = {
   matchPattern
 };
 
+
+

package/utils/schemaCache.js

@@ -0,0 +1,60 @@
+/**
+ * Schema Cache
+ * Caches compiled Zod schemas per file path
+ */
+
+const cache = new Map();
+
+/**
+ * Get cached schema for a file path
+ * @param {string} filePath - Absolute file path
+ * @returns {Object|undefined} Compiled schema or undefined
+ */
+function get(filePath) {
+  return cache.get(filePath);
+}
+
+/**
+ * Set compiled schema for a file path
+ * @param {string} filePath - Absolute file path
+ * @param {Object} schema - Compiled schema object
+ */
+function set(filePath, schema) {
+  cache.set(filePath, schema);
+}
+
+/**
+ * Check if schema exists in cache
+ * @param {string} filePath - Absolute file path
+ * @returns {boolean}
+ */
+function has(filePath) {
+  return cache.has(filePath);
+}
+
+/**
+ * Clear all cached schemas
+ * Useful for development hot-reload
+ */
+function clear() {
+  cache.clear();
+}
+
+/**
+ * Delete a specific schema from cache
+ * @param {string} filePath - Absolute file path
+ * @returns {boolean} True if deleted
+ */
+function del(filePath) {
+  return cache.delete(filePath);
+}
+
+module.exports = {
+  get,
+  set,
+  has,
+  clear,
+  del
+};
+
+