@forgebase/sdk 0.0.1 → 0.0.2

package/README.md

@@ -1,64 +1,27 @@
 # ForgeBase TypeScript SDK
 
-A powerful, type-safe TypeScript SDK for interacting with ForgeBase services, providing comprehensive database operations, real-time features, and advanced query capabilities.
+A powerful, type-safe TypeScript SDK for interacting with ForgeBase services, providing comprehensive database operations, advanced query capabilities, and type safety.
 
 ## Core Features
 
 - **Type-Safe Query Builder**:
   - Fluent API design
-  - Advanced filtering
+  - Advanced filtering (`where`, `whereIn`, `whereExists`, etc.)
   - Complex joins and relations
-  - Aggregations and window functions
-  - Transaction support
-  - Raw query support
-  - Query optimization
+  - Aggregations (`count`, `sum`, `avg`, `min`, `max`)
+  - Window functions (`rowNumber`, `rank`, `lag`, `lead`)
+  - Recursive CTEs
+  - Result transformations (`pivot`, `compute`)
 
 - **Database Operations**:
-  - CRUD operations
+  - CRUD operations (`create`, `update`, `delete`)
   - Batch operations
-  - Pagination
-  - Sorting
-  - Custom queries
-  - Schema validation
-  - Error handling
-
-- **Security Features**:
-
-  <!-- - JWKS support
-  - Token validation
-  - Request signing -->
-  - Input sanitization
-  - Type validation
-  - Error boundaries
-  <!-- - Rate limiting -->
-
-- **Advanced Querying**:
-  - Window functions
-  - Common Table Expressions (CTEs)
-  - Recursive queries
-  - Complex filtering
-  - Advanced joins
-  - Subqueries
-  - Aggregations
-
-<!-- - **Real-time Features**:
-
-  - Live queries
-  - Change notifications
-  - WebSocket integration
-  - Presence tracking
-  - Subscription management
-  - Connection handling
-  - Event buffering -->
-
-<!-- - **Performance Features**:
-  - Query caching
-  - Connection pooling
-  - Batch operations
-  - Lazy loading
-  - Query optimization
-  - Result transformation
-  - Memory management -->
+  - Pagination (`limit`, `offset`)
+  - Sorting (`orderBy`)
+
+- **Security & Validation**:
+  - Input validation
+  - Type inference from your interfaces
 
 ## Installation
 
@@ -72,35 +35,59 @@ pnpm add @forgebase/sdk
 
 ## Basic Usage
 
-### Database Operations
+### Initialization
+
+First, define your database schema and initialize the SDK. This provides automatic type safety across your entire application.
 
 ```typescript
 import { DatabaseSDK } from '@forgebase/sdk/client';
 
-// Initialize with your API URL
-const db = new DatabaseSDK('http://localhost:3000', {
-  credentials: 'include',
-  headers: {
-    'Content-Type': 'application/json',
+// 1. Define your entity types
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+  status: 'active' | 'inactive';
+}
+
+interface Order {
+  id: number;
+  user_id: number;
+  amount: number;
+  status: 'pending' | 'completed';
+}
+
+// 2. Define your Database Schema
+interface Schema {
+  users: User;
+  orders: Order;
+}
+
+// 3. Initialize the SDK with your Schema
+const db = new DatabaseSDK<Schema>({
+  baseUrl: 'http://localhost:3000',
+  axiosConfig: {
+    withCredentials: true,
+    headers: { 'Content-Type': 'application/json' },
   },
 });
+```
 
-// Basic CRUD Operations
-const users = await db
-  .table('users')
-  .select('id', 'name', 'email')
-  .where('status', 'active')
-  .execute({
-    headers: {
-      'some-stuff': 'true',
-    },
-  });
+### Database Operations
 
-// Create a new record
+The SDK automatically infers types based on your Schema.
+
+```typescript
+// Query users (Type is inferred as User[])
+const users = await db.table('users').select('id', 'name', 'email').where('status', 'active').query();
+
+// Create a new record (Type checking ensures payload matches User)
 const newUser = await db.table('users').create({
   name: 'John Doe',
   email: 'john@example.com',
   role: 'user',
+  status: 'active',
 });
 
 // Update a record
@@ -115,74 +102,33 @@ await db.table('users').delete(1);
 ### Advanced Queries
 
 ```typescript
-// Complex filtering with type safety
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  role: string;
-  department: string;
-  salary: number;
-}
-
+// Complex filtering
 const results = await db
-  .table<User>('users')
+  .table('users') // Type inferred automatically
   .where('status', 'active')
   .andWhere((query) => {
-    query.where('role', 'manager').where('department', 'IT').orWhere('salary', '>', 100000);
+    query.where('role', 'admin').orWhere('email', 'like', '%@company.com');
   })
   .orderBy('name', 'asc')
   .limit(10)
-  .execute();
+  .query();
 
 // Aggregations
-const stats = await db.table<User>('users').groupBy('department').select('department').count('id', 'total_users').avg('salary', 'avg_salary').having('total_users', '>', 5).execute();
+const stats = await db.table('orders').groupBy('status').sum('amount', 'total_amount').count('id', 'order_count').having('total_amount', '>', 5000).query();
+
+// Result type is narrowed:
+// stats.data -> { status: string, total_amount: number, order_count: number }[]
 
 // Window Functions
 const rankedUsers = await db
-  .table<User>('users')
+  .table('users')
   .select('name', 'department', 'salary')
-  .window('rank', 'salary_rank', {
-    partitionBy: ['department'],
-    orderBy: [{ field: 'salary', direction: 'desc' }],
-  })
-  .execute();
-
-// Advanced Window Functions
-const analysis = await db
-  .table<User>('users')
-  .windowAdvanced('sum', 'running_total', {
-    field: 'salary',
-    over: {
-      partitionBy: ['department'],
-      orderBy: [{ field: 'hire_date', direction: 'asc' }],
-      frame: {
-        type: 'ROWS',
-        start: 'UNBOUNDED PRECEDING',
-        end: 'CURRENT ROW',
-      },
-    },
-  })
-  .execute();
-```
-
-### CTEs and Recursive Queries
-
-```typescript
-// Simple CTE
-const highPaidUsers = db.table<User>('users').where('salary', '>', 100000);
-
-const result = await db.table<User>('users').with('high_paid', highPaidUsers).execute();
-
-// Recursive CTE
-interface Category {
-  id: number;
-  parent_id: number | null;
-  name: string;
-}
+  .rank('salary_rank', ['department'], [{ field: 'salary', direction: 'desc' }])
+  .query();
 
+// Recursive CTEs (e.g., for hierarchical data)
 const categories = await db
-  .table<Category>('categories')
+  .table('categories')
   .withRecursive(
     'category_tree',
     // Initial query
@@ -191,199 +137,42 @@ const categories = await db
     db.table('categories').join('category_tree', 'parent_id', 'id'),
     { unionAll: true },
   )
-  .execute();
+  .query();
 ```
 
-<!-- ### Real-time Subscriptions
+### Transformations
 
-```typescript
-// Subscribe to changes
-const unsubscribe = await db
-  .table<User>('users')
-  .where('department', 'IT')
-  .subscribe({
-    onAdd: (user) => console.log('New user:', user),
-    onChange: (user) => console.log('User updated:', user),
-    onDelete: (id) => console.log('User deleted:', id),
-  });
-
-// Later: cleanup subscription
-unsubscribe();
-``` -->
-
-<!-- ### Security Features
+You can transform the result set on the client side using `pivot` or `compute`.
 
 ```typescript
-// JWKS Configuration
-const db = new DatabaseSDK('http://localhost:3000', {
-  auth: {
-    jwksUrl: '/.well-known/jwks.json',
-    audience: 'your-api',
-    issuer: 'your-auth-server',
-  },
-});
-
-// Request Signing
-const db = new DatabaseSDK('http://localhost:3000', {
-  security: {
-    signRequests: true,
-    privateKey: 'your-private-key',
-    keyId: 'your-key-id',
-  },
-});
-
-// Rate Limiting
-const db = new DatabaseSDK('http://localhost:3000', {
-  rateLimit: {
-    maxRequests: 100,
-    windowMs: 60000, // 1 minute
-  },
-});
-``` -->
+// Pivot data
+const pivoted = await db.table('sales').pivot('month', ['Jan', 'Feb', 'Mar'], { type: 'sum', field: 'amount' }).query();
+
+// Compute new fields
+const computed = await db
+  .table('employees')
+  .compute({
+    fullName: (row) => `${row.firstName} ${row.lastName}`,
+    tax: (row) => row.salary * 0.2,
+  })
+  .query();
+```
 
 ## Error Handling
 
+The SDK throws standard errors that you can catch and handle.
+
 ```typescript
 try {
-  const result = await db.table('users').where('id', 1).execute();
+  await db.table('users').create(data);
 } catch (error) {
-  if (error instanceof QueryError) {
-    // Handle query-related errors
-    console.error('Query Error:', error.message);
-  } else if (error instanceof ValidationError) {
-    // Handle validation errors
-    console.error('Validation Error:', error.details);
-  } else if (error instanceof AuthorizationError) {
-    // Handle authorization errors
-    console.error('Authorization Error:', error.message);
-  } else {
-    // Handle other errors
-    console.error('Unknown Error:', error);
-  }
+  console.error('Failed to create user:', error.message);
 }
 ```
 
-<!--
-## Advanced Configuration
-
-```typescript
-const db = new DatabaseSDK('http://localhost:3000', {
-  // Authentication
-  credentials: 'include',
-  headers: {
-    Authorization: 'Bearer your-token',
-  },
-
-  // Query Options
-  queryConfig: {
-    maxLimit: 1000,
-    defaultLimit: 50,
-    maxComplexity: 10,
-  },
-
-  // Cache Configuration
-  cache: {
-    enabled: true,
-    ttl: 300, // 5 minutes
-    maxSize: 100, // Maximum number of cached queries
-  },
-
-  // Real-time Configuration
-  realtime: {
-    enabled: true,
-    reconnectDelay: 1000,
-    maxRetries: 5,
-  },
-
-  // Performance Tuning
-  performance: {
-    batchSize: 1000,
-    poolSize: 10,
-    timeout: 5000,
-  },
-});
-``` -->
-
-## Type Safety
-
-The SDK provides full TypeScript support with generic types:
+## Real-time Updates
 
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  role: string;
-}
-
-interface Order {
-  id: number;
-  userId: number;
-  total: number;
-  status: string;
-}
-
-// Type-safe queries
-const users = await db.table<User>('users').select('id', 'name', 'email').where('role', 'admin').execute();
-
-// Type-safe joins
-const orders = await db.table<Order>('orders').join<User>('users', 'userId', 'id').select('orders.id', 'users.name', 'orders.total').execute();
-```
-
-## Performance Optimization
-
-### Query Optimization
-
-```typescript
-// Use select to limit returned fields
-const users = await db.table('users').select('id', 'name').where('active', true).execute();
-
-// Use indexes effectively
-const result = await db
-  .table('users')
-  .where('email', 'user@example.com') // Assuming email is indexed
-  .first()
-  .execute();
-
-// Batch operations (WIP*)
-await db.table('users').createMany([
-  { name: 'User 1', email: 'user1@example.com' },
-  { name: 'User 2', email: 'user2@example.com' },
-]);
-```
-
-<!-- ### Caching
-
-```typescript
-// Enable caching for specific queries
-const users = await db
-  .table('users')
-  .cache({
-    ttl: 300, // 5 minutes
-    tags: ['users'],
-  })
-  .execute();
-
-// Invalidate cache
-await db.invalidateCache('users');
-``` -->
-
-## Building
-
-Run `nx build sdk` to build the library.
-
-## Running Tests
-
-```bash
-# Run unit tests
-nx test sdk
-
-# Run integration tests
-nx test sdk --config=integration
-
-# Run tests with coverage
-nx test sdk --coverage
-```
+> ⚠️ **Note**: Real-time features (WebSockets/SSE) are currently experimental and under active development. They are not yet fully documented or recommended for production use.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgebase/sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": false,
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -49,10 +49,10 @@
   "dependencies": {
     "axios": "^1.7.9",
     "kysely": "^0.28.11",
-    "@forgebase/database": "0.0.1"
+    "@forgebase/database": "0.0.2"
   },
   "peerDependencies": {
-    "@forgebase/database": "0.0.1"
+    "@forgebase/database": "0.0.2"
   },
   "devDependencies": {
     "tslib": "^2.3.0",