@gl-life/gl-life-database 1.0.0 → 1.1.0

package/API.md

@@ -1,6 +1,6 @@
 # @gl-life/gl-life-database API Reference
 
-**Version**: 1.0.0
+**Version**: 1.1.0
 **Package**: `@gl-life/gl-life-database`
 **License**: Apache-2.0
 **Homepage**: https://gl.life
@@ -805,6 +805,254 @@ Rollback migrations.
 
 ---
 
+## Flex Table System
+
+The Flex Table System provides dynamic schema capabilities without ALTER TABLE operations. From `gl-life-data`.
+
+### MetaDataService
+
+Manages metadata mappings between logical and physical field names.
+
+#### Constructor
+
+```typescript
+class MetaDataService {
+  constructor(dbPath: string);
+}
+```
+
+**Parameters**:
+- `dbPath: string` - Path to SQLite database containing metadata
+
+#### Methods
+
+##### createMapping()
+
+```typescript
+createMapping(input: CreateMappingInput): Promise<MetadataSelect>
+```
+
+Creates a new metadata mapping, automatically assigning the next available physical field.
+
+**Parameters**:
+```typescript
+interface CreateMappingInput {
+  tableName: string;
+  logicalFieldName: string;
+  dataType: 'string' | 'int' | 'decimal' | 'date' | 'boolean' | 'text' | 'datetime' | 'float' | 'bigint' | 'uuid';
+  isRequired?: boolean;
+  defaultValue?: string | null;
+  validationRules?: ValidationRules;
+  description?: string;
+  displayOrder?: number;
+  isIndexed?: boolean;
+  isUnique?: boolean;
+  foreignKeyRef?: string | null;
+  createdBy?: string;
+}
+```
+
+**Returns**: `Promise<MetadataSelect>` - Created metadata entry
+
+**Example**:
+```typescript
+const metaDataService = new MetaDataService('./database.db');
+
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'productName',
+  dataType: 'string',        // Will map to string_field_1
+  isRequired: true,
+  description: 'Product name'
+});
+```
+
+##### getMappingByLogicalField()
+
+```typescript
+getMappingByLogicalField(tableName: string, logicalFieldName: string): MetadataSelect | null
+```
+
+**Parameters**:
+- `tableName: string` - Entity table name
+- `logicalFieldName: string` - Logical field name to look up
+
+**Returns**: `MetadataSelect | null` - Metadata entry or null if not found
+
+##### getTableMappings()
+
+```typescript
+getTableMappings(tableName: string): MetadataSelect[]
+```
+
+**Parameters**:
+- `tableName: string` - Entity table name
+
+**Returns**: `MetadataSelect[]` - All metadata mappings for the table
+
+### Using Flex Tables with TypeSafeQueryBuilder
+
+```typescript
+import { TypeSafeQueryBuilder, Logger } from '@gl-life/gl-life-database';
+import { MetaDataService } from 'gl-life-data';
+
+const logger = new Logger({ level: 'info' });
+const metaDataService = new MetaDataService('./database.db');
+
+// Create mappings
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'name',
+  dataType: 'string'           // Maps to string_field_1
+});
+
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'price',
+  dataType: 'decimal'          // Maps to decimal_field_1
+});
+
+// Query using logical field names
+const builder = new TypeSafeQueryBuilder('products', metaDataService, logger);
+const sql = builder
+  .select(['name', 'price'])   // Logical names
+  .where('price', '>', 100)
+  .toSQL();
+
+// Generates: SELECT string_field_1, decimal_field_1
+//            FROM flex_table
+//            WHERE decimal_field_1 > ?
+```
+
+### Flex Table Schema
+
+Universal schema for all Flex tables:
+
+```sql
+CREATE TABLE flex_table (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT,
+
+  -- String fields (10 slots)
+  string_field_1 TEXT,
+  string_field_2 TEXT,
+  string_field_3 TEXT,
+  ...
+  string_field_10 TEXT,
+
+  -- Integer fields (10 slots)
+  int_field_1 INTEGER,
+  int_field_2 INTEGER,
+  ...
+  int_field_10 INTEGER,
+
+  -- Decimal fields (10 slots)
+  decimal_field_1 REAL,
+  ...
+  decimal_field_10 REAL,
+
+  -- Date fields (10 slots)
+  date_field_1 TEXT,
+  ...
+  date_field_10 TEXT,
+
+  -- Boolean fields (10 slots)
+  boolean_field_1 INTEGER,
+  ...
+  boolean_field_10 INTEGER,
+
+  -- Text fields (10 slots)
+  text_field_1 TEXT,
+  ...
+  text_field_10 TEXT,
+
+  -- Additional field types (10 slots each):
+  -- datetime_field_1 through datetime_field_10
+  -- float_field_1 through float_field_10
+  -- bigint_field_1 through bigint_field_10
+  -- uuid_field_1 through uuid_field_10
+
+  -- Overflow for extra fields
+  json_data TEXT,
+
+  -- Timestamps
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### Metadata Table Schema
+
+```sql
+CREATE TABLE metadata (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT,                      -- NULL for shared, or specific tenant ID
+  table_name TEXT NOT NULL,
+  logical_field_name TEXT NOT NULL,
+  physical_column_name TEXT NOT NULL,
+  data_type TEXT NOT NULL,
+  is_required INTEGER NOT NULL DEFAULT 0,
+  default_value TEXT,
+  validation_rules TEXT,               -- JSON
+  description TEXT,
+  display_order INTEGER,
+  is_indexed INTEGER NOT NULL DEFAULT 0,
+  is_unique INTEGER NOT NULL DEFAULT 0,
+  foreign_key_ref TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by TEXT,
+  updated_by TEXT,
+  UNIQUE(tenant_id, table_name, logical_field_name),
+  UNIQUE(tenant_id, table_name, physical_column_name)
+);
+```
+
+### Flex Tables + Multi-Tenancy
+
+Combine Flex tables with multi-tenancy for per-tenant custom fields:
+
+```typescript
+// Shared field for all tenants
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'name',
+  dataType: 'string'
+});
+
+// Tenant-specific field (Tenant A only)
+await connection.execute(`
+  INSERT INTO metadata (
+    id, tenant_id, table_name, logical_field_name,
+    physical_column_name, data_type
+  ) VALUES (?, ?, ?, ?, ?, ?)
+`, [
+  'tenantA_products_warranty',
+  'tenant-A',
+  'products',
+  'warrantyMonths',
+  'int_field_1',               // Tenant A uses int_field_1
+  'int'
+]);
+
+// Tenant-specific field (Tenant B only)
+await connection.execute(`
+  INSERT INTO metadata (
+    id, tenant_id, table_name, logical_field_name,
+    physical_column_name, data_type
+  ) VALUES (?, ?, ?, ?, ?, ?)
+`, [
+  'tenantB_products_size',
+  'tenant-B',
+  'products',
+  'size',
+  'string_field_2',            // Tenant B uses string_field_2
+  'string'
+]);
+```
+
+---
+
 ## CloudForge Adapters
 
 ### D1Adapter

package/README.md

@@ -9,6 +9,7 @@ Enhanced gl-life-data wrapper with CloudForge features - Type-safe database abst
 ### Key Features
 
 - 🗄️ **Type-Safe Query Builder** - Fluent API with full TypeScript support extending gl-life-data
+- 🔀 **Flex Table System** - Dynamic schema without ALTER TABLE, metadata-driven field mapping
 - 👥 **Multi-Tenancy** - Built-in tenant isolation with Row-Level Security (RLS)
 - ⚡ **Caching Layer** - High-performance query result caching with memory and Cloudflare KV backends
 - 🔄 **Migrations** - Version-controlled database migrations with rollback support
@@ -180,6 +181,72 @@ export default {
 };
 ```
 
+### Flex Table System
+
+The Flex Table System is a powerful feature from gl-life-data that provides dynamic schema capabilities without ALTER TABLE operations. Perfect for multi-tenant SaaS applications where each tenant needs custom fields.
+
+```typescript
+import { TypeSafeQueryBuilder, Logger } from '@gl-life/gl-life-database';
+import { MetaDataService } from 'gl-life-data';
+
+// Initialize metadata service
+const metaDataService = new MetaDataService('./database.db');
+
+// Create metadata mapping: logical field → physical column
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'productName',
+  dataType: 'string',          // Maps to string_field_1
+  isRequired: true,
+  description: 'Product name'
+});
+
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'price',
+  dataType: 'decimal',         // Maps to decimal_field_1
+  isRequired: true
+});
+
+// Query using logical field names
+const builder = new TypeSafeQueryBuilder('products', metaDataService, logger);
+const sql = builder
+  .select(['productName', 'price'])  // Uses logical names
+  .where('price', '>', 100)
+  .toSQL();
+// Generates: SELECT string_field_1, decimal_field_1 FROM flex_table WHERE decimal_field_1 > ?
+```
+
+**Key Benefits:**
+- **Universal Schema**: All tables use same physical structure (string_field_1, int_field_1, etc.)
+- **No ALTER TABLE**: Add fields by creating metadata entries
+- **Type Safety**: 10 fields per data type (string, int, decimal, date, boolean, text, datetime, float, bigint, uuid)
+- **Multi-Tenant Ready**: Different tenants can have different custom fields
+- **Query Transparency**: Use logical field names, metadata handles physical mapping
+
+**Flex Table Schema:**
+```sql
+CREATE TABLE flex_table (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT,
+  -- 10 string fields
+  string_field_1 TEXT,
+  string_field_2 TEXT,
+  ...
+  string_field_10 TEXT,
+  -- 10 int fields
+  int_field_1 INTEGER,
+  ...
+  int_field_10 INTEGER,
+  -- Plus: decimal, date, boolean, text, datetime, float, bigint, uuid fields
+  json_data TEXT,           -- Overflow for extra fields
+  created_at TEXT,
+  updated_at TEXT
+);
+```
+
+See [examples/06-flex-tables.ts](./examples/06-flex-tables.ts) and [examples/07-flex-with-multi-tenancy.ts](./examples/07-flex-with-multi-tenancy.ts) for complete workflows.
+
 ## Usage
 
 ### Query Builder

package/dist/index.cjs

@@ -4719,7 +4719,7 @@ var R2BackupAdapter = class {
 };
 
 // src/index.ts
-var version = "1.0.0";
+var version = "1.1.0";
 
 Object.defineProperty(exports, "Config", {
   enumerable: true,