@neupgroup/mapper 1.2.0 → 1.2.2

package/README.md

@@ -1,37 +1,706 @@
-# @neupgroup/mapper
-
-Core library for Neup.Mapper. Provides simple schema registration utilities that can be expanded over time.
-
-## Install
-
-```bash
-npm install @neupgroup/mapper
-```
-
-## Usage
-
-```ts
-import Mapper from '@neupgroup/mapper';
-
-const mapper = new Mapper();
-
-mapper.register({
-  name: 'User',
-  fields: [
-    { name: 'id', type: 'string' },
-    { name: 'email', type: 'string' },
-    { name: 'createdAt', type: 'date' },
-  ],
-});
-
-console.log(mapper.list());
-```
-
-## Build
-
-```bash
-npx tsc -p ./tsconfig.json
-```
-
-Outputs are generated to `dist/` with type declarations.
+# @neupgroup/mapper
+
+Schema and mapping utilities with lightweight ORM helpers. Define schemas, attach adapters per connection, and perform CRUD with a simple, fluent API.
+
+## Installation
+
+```bash
+npm install @neupgroup/mapper
+```
+
+## 🚀 Quick Start Options
+
+### **Option 1: One-Import Quick Start**
+**The simplest way to get started - just import and use:**
+
+```ts
+import Mapper from '@neupgroup/mapper'
+
+// 1. Define a schema (Mapper auto-configures with sensible defaults)
+Mapper.schema('users')
+  .use({ connection: 'default', collection: 'users' })
+  .setStructure([
+    { name: 'id', type: 'int', autoIncrement: true },
+    { name: 'name', type: 'string' },
+    { name: 'email', type: 'string' }
+  ])
+
+// 2. Use immediately - no setup required!
+await Mapper.add('users', { name: 'Alice', email: 'alice@example.com' })
+const users = await Mapper.get('users')
+const user = await Mapper.getOne('users', { email: 'alice@example.com' })
+await Mapper.update('users', { email: 'alice@example.com' }, { name: 'Alice Cooper' })
+await Mapper.delete('users', { email: 'alice@example.com' })
+```
+
+### **Option 2: Configuration-Based Approach**
+**Use configuration files to manage connections and schemas:**
+
+```ts
+import { createConfigMapper } from '@neupgroup/mapper'
+
+// Define your configuration
+const config = {
+  connections: [
+    ['mydb', 'sql', 'user', 'myapp', 'localhost', 5432],
+    ['myapi', 'api', 'https://api.example.com']
+  ],
+  schemas: {
+    users: {
+      connection: 'mydb',
+      collection: 'users',
+      structure: [
+        { name: 'id', type: 'int', autoIncrement: true },
+        { name: 'name', type: 'string' },
+        { name: 'email', type: 'string' }
+      ]
+    }
+  }
+}
+
+// Create mapper from config
+const mapper = createConfigMapper(config)
+
+// Use the mapper
+await mapper.useConnection('mydb').table('users').add({ name: 'Alice', email: 'alice@example.com' })
+const users = await mapper.useConnection('mydb').table('users').select().execute()
+```
+
+### **Option 3: PHP-Style Fluent API**
+**Use static method chaining for dynamic connections:**
+
+```ts
+import { StaticMapper as Mapper } from '@neupgroup/mapper'
+
+// Create persistent connections
+Mapper.makeConnection('mydb', 'mysql', {
+  host: 'localhost',
+  user: 'root', 
+  password: 'password',
+  database: 'myapp'
+})
+
+// Use connections with method chaining
+const users = await Mapper.useConnection('mydb')
+  .table('users')
+  .select()
+  .where('active', true)
+  .execute()
+
+// Create temporary connections on-the-fly
+const tempData = await Mapper.makeTempConnection('mongodb', {
+  url: 'mongodb://localhost:27017',
+  database: 'temp'
+})
+  .collection('cache')
+  .find({ expired: false })
+  .execute()
+```
+
+### **Auto-Configuration Magic** ✨
+
+The Mapper automatically configures itself based on your environment:
+
+- **Environment Variables**: `DATABASE_URL=mysql://user:pass@host:port/db`
+- **Browser Global**: `window.__MAPPER_CONFIG__`
+- **Default Fallback**: In-memory API connection for instant prototyping
+
+**Connection type auto-detection:**
+```
+mysql://...      → MySQL
+postgres://...   → PostgreSQL  
+mongodb://...    → MongoDB
+firestore://...  → Firestore
+```
+
+### **Manual Configuration (Optional)**
+
+```ts
+// Connect to your database
+Mapper.connect('mydb', 'mysql', {
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'myapp'
+})
+
+// Or use environment variables
+// DATABASE_URL=mysql://root:password@localhost:3306/myapp
+```
+
+## 🛠️ Complete Usage Examples
+
+### **Example 1: Zero-Configuration Setup**
+```ts
+import Mapper from '@neupgroup/mapper'
+
+// Works immediately with in-memory storage
+const users = await Mapper.get('users') // Returns empty array
+```
+
+### **Example 2: Environment-Based Configuration**
+```bash
+# Set environment variable
+export DATABASE_URL=mysql://user:password@localhost:3306/myapp
+
+# Or in browser
+window.__MAPPER_CONFIG__ = {
+  connection: {
+    name: 'mydb',
+    type: 'mysql',
+    key: { host: 'localhost', user: 'root', password: 'pass', database: 'myapp' }
+  }
+}
+```
+
+```ts
+import Mapper from '@neupgroup/mapper'
+
+// Automatically configured from environment
+const users = await Mapper.get('users')
+```
+
+### **Example 3: Schema with Multiple Field Types**
+```ts
+import Mapper from '@neupgroup/mapper'
+
+Mapper.schema('products')
+  .use({ connection: 'default', collection: 'products' })
+  .setStructure([
+    { name: 'id', type: 'int', autoIncrement: true },
+    { name: 'name', type: 'string' },
+    { name: 'price', type: 'number' },
+    { name: 'inStock', type: 'boolean' },
+    { name: 'createdAt', type: 'date' },
+    { name: 'categoryId', type: 'int' }
+  ])
+
+// Add product
+await Mapper.add('products', {
+  name: 'Laptop',
+  price: 999.99,
+  inStock: true,
+  createdAt: new Date(),
+  categoryId: 1
+})
+
+// Get products with filters
+const expensiveProducts = await Mapper.get('products', { price: 500 }, '>')
+const inStockProducts = await Mapper.get('products', { inStock: true })
+```
+
+### **Example 4: Advanced Query Operations**
+```ts
+import Mapper from '@neupgroup/mapper'
+
+// Complex queries using the underlying API
+const query = Mapper.use('users')
+  .where('age', 18, '>=')
+  .where('status', 'active')
+
+const activeAdults = await query.get()
+const firstActiveAdult = await query.getOne()
+
+// Update multiple records
+await query.to({ lastLogin: new Date() }).update()
+
+// Delete with complex conditions
+await Mapper.use('users')
+  .where('lastLogin', new Date('2023-01-01'), '<')
+  .delete()
+```
+
+### **Example 5: Multiple Databases**
+```ts
+import Mapper from '@neupgroup/mapper'
+
+// Connect to multiple databases
+Mapper.connect('mysql_db', 'mysql', {
+  host: 'localhost',
+  user: 'root',
+  password: 'password',
+  database: 'main_app'
+})
+
+Mapper.connect('mongo_cache', 'mongodb', {
+  uri: 'mongodb://localhost:27017',
+  database: 'cache'
+})
+
+// Use different connections for different schemas
+Mapper.schema('users')
+  .use({ connection: 'mysql_db', collection: 'users' })
+  .setStructure([...])
+
+Mapper.schema('sessions')
+  .use({ connection: 'mongo_cache', collection: 'sessions' })
+  .setStructure([...])
+
+// Query from different databases
+const users = await Mapper.get('users')        // From MySQL
+const sessions = await Mapper.get('sessions')    // From MongoDB
+```
+
+## 🌍 Environment Configuration Guide
+
+### **Node.js Environment Variables**
+
+The Mapper automatically detects these environment variables:
+
+```bash
+# Basic database URL (auto-detects type)
+DATABASE_URL=mysql://user:password@localhost:3306/myapp
+
+# Or specific connection types
+MYSQL_URL=mysql://user:password@localhost:3306/myapp
+POSTGRES_URL=postgres://user:password@localhost:5432/myapp
+MONGODB_URL=mongodb://localhost:27017/myapp
+FIRESTORE_URL=firestore://project-id
+```
+
+### **Browser Environment**
+
+For client-side applications, use the global configuration:
+
+```html
+<script>
+  window.__MAPPER_CONFIG__ = {
+    connection: {
+      name: 'api',
+      type: 'api',
+      key: {
+        endpoint: 'https://api.example.com',
+        apiKey: 'your-api-key'
+      }
+    },
+    schemas: [
+      {
+        name: 'users',
+        connection: 'api',
+        collection: 'users',
+        structure: [
+          { name: 'id', type: 'int' },
+          { name: 'name', type: 'string' }
+        ]
+      }
+    ]
+  }
+</script>
+```
+
+### **Configuration Priority Order**
+
+1. **Manual Configuration**: `Mapper.connect()` calls
+2. **Environment Variables**: `DATABASE_URL` and others
+3. **Browser Global**: `window.__MAPPER_CONFIG__`
+4. **Default Fallback**: In-memory API connection
+
+### **Docker & Production Setup**
+
+```dockerfile
+# Dockerfile
+ENV DATABASE_URL=mysql://user:password@db:3306/myapp
+```
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    environment:
+      - DATABASE_URL=mysql://user:password@db:3306/myapp
+```
+
+### **Configuration Validation**
+
+```ts
+import Mapper from '@neupgroup/mapper'
+
+// Check current configuration
+console.log('Connections:', Mapper.getConnections().list())
+console.log('Schemas:', Mapper.getSchemaManager().list())
+
+// Verify auto-configuration worked
+const config = Mapper.getConnections().get('default')
+if (!config) {
+  console.log('No auto-configuration detected, using manual setup...')
+  Mapper.connect('manual', 'mysql', { /* config */ })
+}
+```
+
+## Advanced Usage (Original API)
+
+For more control, you can still use the original granular API:
+
+```ts
+import { connection, schema } from '@neupgroup/mapper'
+import type { DbAdapter, QueryOptions } from '@neupgroup/mapper'
+
+// 1) Define connections
+const conRegistry = connection()
+conRegistry.create('mysql_prod', 'mysql').key({
+  host: '127.0.0.1',
+  port: 3306,
+  user: 'root',
+  password: 's3cr3t',
+  database: 'appdb',
+})
+
+// 2) Attach an adapter for the connection
+const adapter: DbAdapter = {
+  async getDocuments(options: QueryOptions) { return [] },
+  async addDocument(collectionName: string, data: Record<string, any>) { return 'new-id' },
+  async updateDocument(collectionName: string, docId: string, data: Record<string, any>) { },
+  async deleteDocument(collectionName: string, docId: string) { },
+}
+conRegistry.attachAdapter('mysql_prod', adapter)
+
+// 3) Register schema and run CRUD
+const sm = schema(conRegistry)
+sm.create('User')
+  .use({ connection: 'mysql_prod', collection: 'users' })
+  .setStructure({
+    id: 'string',
+    email: 'string',
+    name: 'string editable',
+    createdAt: 'date',
+    '?field': 'allow-undefined',
+  })
+
+const User = sm.use('User')
+await User.add({ id: 'u_1', email: 'alice@example.com', name: 'Alice', createdAt: new Date() })
+await User.where(['id', 'u_1']).to({ name: 'Alice Cooper' }).updateOne()
+const one = await User.where(['id', 'u_1']).getOne()
+await User.where(['id', 'u_1']).deleteOne()
+
+## Connections DSL
+
+You can define connections in a simple DSL and load them at runtime.
+
+`connections.dsl` example:
+
+```
+connections = [
+  mysql_prod = [
+    type: mysql,
+    host: 127.0.0.1,
+    port: 3306,
+    user: root,
+    password: "s3cr3t",
+    database: appdb,
+  ],
+
+  mongo_dev = [
+    type: mongodb,
+    uri: "mongodb://127.0.0.1:27017",
+    database: devdb,
+  ],
+]
+```
+
+Load and normalize:
+
+```ts
+import { parseConnectionsDsl, toNormalizedConnections, connection, schema } from '@neupgroup/mapper'
+
+const text = await fs.promises.readFile('connections.dsl', 'utf8')
+const envMap = parseConnectionsDsl(text)
+const conns = toNormalizedConnections(envMap)
+
+const conRegistry = connection()
+for (const c of conns) {
+  conRegistry.register({ name: c.name, type: c.type, key: c.key })
+}
+const sm = schema(conRegistry)
+```
+
+Notes:
+- `type` (or `dbType`) defaults to `api` if omitted.
+- Values can be quoted or unquoted; `#` comments are ignored.
+
+## Adapters
+
+Adapters implement backend-specific operations. Shape:
+
+```ts
+export interface DbAdapter {
+  get?(options: QueryOptions): Promise<any[]>
+  getOne?(options: QueryOptions): Promise<any | null>
+  getDocuments(options: QueryOptions): Promise<any[]>
+  addDocument(collectionName: string, data: Record<string, any>): Promise<string>
+  updateDocument(collectionName: string, docId: string, data: Record<string, any>): Promise<void>
+  deleteDocument(collectionName: string, docId: string): Promise<void>
+}
+```
+
+Attach to a connection with `conRegistry.attachAdapter('<name>', adapter)` before querying.
+
+## Schemas & Structure
+
+Define schemas with a descriptor object or explicit fields array:
+
+```ts
+sm.create('Product')
+  .use({ connection: 'mysql_prod', collection: 'products' })
+  .setStructure({
+    id: 'string',
+    title: 'string editable',
+    price: 'number',
+    createdAt: 'date',
+    '?field': 'allow-undefined',
+  })
+```
+
+Field tokens:
+- `type`: one of `string`, `number`, `boolean`, `date`, `int`.
+- `editable`: marks commonly modified fields.
+- `'?field'`: enables accepting fields not listed in the schema.
+
+## Query & CRUD
+
+Build queries and run operations:
+
+```ts
+const Q = sm.use('Product')
+await Q.add({ id: 'p_1', title: 'Widget', price: 9.99 })
+const items = await Q.where('price', 10, '<').get()
+const one = await Q.where(['id', 'p_1']).getOne()
+await Q.where(['id', 'p_1']).to({ price: 7.99 }).updateOne()
+await Q.where(['id', 'p_1']).deleteOne()
+```
+
+Methods:
+- `where(field, value, operator?)`, `where([field, value])` and `whereComplex(raw)`.
+- `get`, `getOne`, `add`, `delete`, `deleteOne`, `to(update).update`, `updateOne`.
+
+## Documentation Helpers
+
+For apps that want to render built-in documentation:
+
+```ts
+import { documentationMd, markdownToHtml, getDocumentationHtml } from '@neupgroup/mapper'
+
+const html = getDocumentationHtml()
+```
+
+## API Reference
+
+### **Core Functions**
+- `connection()` → create connections registry (see `src/index.ts:299`–`301`)
+- `schema(conns?)` → create `SchemaManager` (see `src/index.ts:303`–`306`)
+- `schemas` → singleton `SchemaManager` (see `src/index.ts:308`–`311`)
+- `createOrm(adapter)` → wrapper around a `DbAdapter` (see `src/orm/index.ts:3`–`27`)
+- `parseConnectionsDsl(text)`, `toNormalizedConnections(map)` (see `src/env.ts:31`–`75`, `87`–`95`)
+- `documentationMd`, `markdownToHtml`, `getDocumentationHtml` (see `src/docs.ts:5`–`275`, `277`–`356`)
+
+### **Configuration-Based API**
+- `createConfigMapper(config)` → Create mapper from configuration object
+- `createDefaultMapper()` → Create mapper with default configuration
+- `ConfigBasedMapper` → Class for configuration-based mapping
+  - `configure(config)` → Configure the mapper
+  - `makeConnection(name, type, config)` → Add connection
+  - `useConnection(name)` → Use specific connection
+  - `getConnection(name)` → Get connection details
+
+### **Fluent API (StaticMapper)**
+- `StaticMapper.makeConnection(name, type, config)` → Create persistent connection
+- `StaticMapper.useConnection(name)` → Use existing connection
+- `StaticMapper.makeTempConnection(type, config)` → Create temporary connection
+- `StaticMapper.getConnection(name)` → Get connection by name
+- `StaticMapper.listConnections()` → List all connections
+
+### **Query Builder Methods**
+- `table(name)` / `collection(name)` → Specify table/collection
+- `select()` / `find()` → Start select query
+- `where(field, value, operator?)` → Add where condition
+- `orderBy(field, direction?)` → Add ordering
+- `limit(count)` → Limit results
+- `execute()` → Execute query
+- `add(data)` → Insert data
+- `update(data)` → Update data
+- `delete()` → Delete data
+
+### **Types**
+- `DbAdapter`, `QueryOptions`, `EnvDslConnections`, `NormalizedConnection`
+- `ConnectionConfig`, `MapperConfig`, `FluentConnectionBuilder`
+- `ConnectionType`: `'sql' | 'mysql' | 'postgres' | 'mongodb' | 'firestore' | 'api'`
+
+## Build & Local Development
+
+```bash
+npm run build
+```
+
+Outputs are generated to `dist/` with type declarations.
+
+## Error Handling & Troubleshooting
+
+- Wrap operations in `try/catch` and handle nulls from `getOne()`.
+- Verify credentials and network connectivity for your backend.
+- Ensure schema field names and types match your storage engine.
+
+---
+
+Copyright © Neup Group
+
+## 🎯 Quick Reference
+
+### **One-Import Benefits**
+
+✅ **Zero Configuration**: Works out of the box  
+✅ **Auto-Detection**: Automatically configures from environment  
+✅ **Universal**: Works in Node.js and browsers  
+✅ **Type Safe**: Full TypeScript support  
+✅ **Progressive**: Start simple, scale to complex  
+✅ **Lightweight**: Minimal overhead, maximum performance  
+
+### **Migration from Original API**
+
+The new `Mapper` default export is fully compatible with the original API:
+
+```ts
+// Old way (still works)
+import { connection, schema } from '@neupgroup/mapper'
+const conns = connection()
+const sm = schema(conns)
+
+// New way (recommended)
+import Mapper from '@neupgroup/mapper'
+// Mapper is pre-configured and ready to use
+
+// Access underlying managers if needed
+const conns = Mapper.getConnections()
+const sm = Mapper.getSchemaManager()
+```
+
+### **Best Practices**
+
+1. **Start with defaults**: Let Mapper auto-configure itself
+2. **Use environment variables**: Set `DATABASE_URL` for production
+3. **Define schemas early**: Create schemas at app startup
+4. **Use TypeScript**: Get full type safety and IntelliSense
+5. **Handle errors**: Wrap operations in try/catch blocks
+
+### **Common Patterns**
+
+```ts
+// Pattern 1: Quick CRUD (One-Import)
+await Mapper.add('users', data)
+const users = await Mapper.get('users')
+
+// Pattern 2: Configuration-Based
+const mapper = createConfigMapper(config)
+await mapper.useConnection('mydb').table('users').add(data)
+
+// Pattern 3: Fluent API
+await StaticMapper.useConnection('mydb').table('users').add(data).execute()
+
+// Pattern 4: Complex queries
+const results = await Mapper.use('users')
+  .where('age', 18, '>=')
+  .where('country', 'US')
+  .get()
+
+// Pattern 5: Batch operations
+const users = await Mapper.get('users')
+for (const user of users) {
+  await Mapper.update('users', { id: user.id }, { lastSeen: new Date() })
+}
+```
+
+## 🔄 **Choosing the Right Approach**
+
+### **When to Use Each Method**
+
+| Approach | Best For | Example Use Case |
+|----------|----------|------------------|
+| **One-Import** | Quick prototyping, simple apps | `Mapper.add('users', data)` |
+| **Configuration-Based** | Enterprise apps, multiple environments | Load from config files |
+| **Fluent API** | Dynamic connections, runtime decisions | Create temp connections on-demand |
+
+### **Migration Between Approaches**
+
+```ts
+// Start with One-Import
+import Mapper from '@neupgroup/mapper'
+await Mapper.add('users', { name: 'Alice' })
+
+// Gradually move to Configuration-Based
+import { createConfigMapper } from '@neupgroup/mapper'
+const mapper = createConfigMapper(config)
+await mapper.useConnection('mydb').table('users').add({ name: 'Alice' })
+
+// Or use Fluent API for dynamic scenarios
+import { StaticMapper } from '@neupgroup/mapper'
+StaticMapper.makeConnection('temp', 'mysql', config)
+await StaticMapper.useConnection('temp').table('users').add({ name: 'Alice' })
+```
+
+### **Real-World Examples**
+
+**Microservices Configuration:**
+```ts
+// config/mapper.config.ts
+export const mapperConfig = {
+  connections: [
+    ['user-service', 'postgres', 'user', 'users_db', 'user-db.internal', 5432],
+    ['order-service', 'mysql', 'order', 'orders_db', 'order-db.internal', 3306],
+    ['analytics-api', 'api', 'https://analytics.internal.company.com']
+  ]
+}
+
+// services/UserService.ts
+import { createConfigMapper } from '@neupgroup/mapper'
+import { mapperConfig } from '../config/mapper.config'
+
+const mapper = createConfigMapper(mapperConfig)
+
+export class UserService {
+  async getUser(id: string) {
+    return await mapper.useConnection('user-service')
+      .table('users')
+      .select()
+      .where('id', id)
+      .execute()
+  }
+}
+```
+
+**Dynamic Connection Management:**
+```ts
+// utils/ConnectionManager.ts
+import { StaticMapper } from '@neupgroup/mapper'
+
+export class ConnectionManager {
+  private activeConnections: Set<string> = new Set()
+
+  async createTenantConnection(tenantId: string, dbConfig: any) {
+    const connectionName = `tenant-${tenantId}`
+    
+    StaticMapper.makeConnection(connectionName, 'mysql', {
+      host: dbConfig.host,
+      database: `tenant_${tenantId}`,
+      user: dbConfig.user,
+      password: dbConfig.password
+    })
+    
+    this.activeConnections.add(connectionName)
+    return connectionName
+  }
+
+  async queryTenant(tenantId: string, table: string) {
+    const connectionName = `tenant-${tenantId}`
+    return await StaticMapper.useConnection(connectionName)
+      .table(table)
+      .select()
+      .execute()
+  }
+
+  cleanupConnection(tenantId: string) {
+    const connectionName = `tenant-${tenantId}`
+    this.activeConnections.delete(connectionName)
+    // Connection cleanup handled automatically
+  }
+}
+```