@forgebase/sdk 0.0.1 → 0.0.3

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/dist/cjs/database/client/client.d.ts

@@ -153,7 +153,7 @@ export interface AuthInterceptors {
         onRejected: (error: any) => Promise<any> | any;
     };
 }
-export declare class DatabaseSDK {
+export declare class DatabaseSDK<Schema extends Record<string, any> = any> {
     private baseUrl;
     private axiosInstance;
     /**
@@ -251,6 +251,7 @@ export declare class DatabaseSDK {
      * Helper method to create a query builder for fluent API usage
      * @param tableName The name of the table to query
      */
+    table<K extends keyof Schema>(tableName: K): QueryBuilder<Schema[K]>;
     table<T extends Record<string, any>>(tableName: string): QueryBuilder<T>;
     /**
      * Validates data object
@@ -260,7 +261,10 @@ export declare class DatabaseSDK {
 /**
  * Query builder class for more fluent API usage
  */
-declare class QueryBuilder<T extends Record<string, any>> {
+/**
+ * Query builder class for more fluent API usage
+ */
+declare class QueryBuilder<T extends Record<string, any>, Result extends Record<string, any> | undefined = undefined> {
     private sdk;
     private tableName;
     private params;
@@ -270,7 +274,7 @@ declare class QueryBuilder<T extends Record<string, any>> {
     /**
      * Add a recursive CTE
      */
-    withRecursive(name: string, initialQuery: QueryBuilder<T>, recursiveQuery: QueryBuilder<T>, options?: {
+    withRecursive(name: string, initialQuery: QueryBuilder<T, any>, recursiveQuery: QueryBuilder<T, any>, options?: {
         unionAll?: boolean;
         columns?: string[];
     }): this;
@@ -285,14 +289,14 @@ declare class QueryBuilder<T extends Record<string, any>> {
     /**
      * Add common window functions
      */
-    rowNumber(alias: string, partitionBy?: string[], orderBy?: OrderByClause<T>[]): this;
-    rank(alias: string, partitionBy?: string[], orderBy?: OrderByClause<T>[]): this;
-    lag(field: string, alias: string, partitionBy?: string[], orderBy?: OrderByClause<T>[]): this;
-    lead(field: string, alias: string, partitionBy?: string[], orderBy?: OrderByClause<T>[]): this;
+    rowNumber(alias: string, partitionBy?: FieldKeys<T>[], orderBy?: OrderByClause<T>[]): this;
+    rank(alias: string, partitionBy?: FieldKeys<T>[], orderBy?: OrderByClause<T>[]): this;
+    lag(field: FieldKeys<T>, alias: string, partitionBy?: FieldKeys<T>[], orderBy?: OrderByClause<T>[]): this;
+    lead(field: FieldKeys<T>, alias: string, partitionBy?: FieldKeys<T>[], orderBy?: OrderByClause<T>[]): this;
     /**
      * Add a CTE (WITH clause)
      */
-    with(name: string, queryOrCallback: QueryBuilder<T> | ((query: QueryBuilder<T>) => void), columns?: FieldKeys<T>[]): this;
+    with(name: string, queryOrCallback: QueryBuilder<T, any> | ((query: QueryBuilder<T, T>) => void), columns?: FieldKeys<T>[]): this;
     /**
      * Transform the result set
      */
@@ -311,18 +315,6 @@ declare class QueryBuilder<T extends Record<string, any>> {
      * @param operator The comparison operator
      * @param value The value to compare against
      * @returns The query builder instance
-     * @example
-     * db.table<User>("users").where("status", "active").execute();
-     * db.table<User>("users").where("age", ">", 18).execute();
-     * db.table<User>("users").where("role", "in", ["admin", "manager"]).execute();
-     * db.table<User>("users").where("created_at", "is not null").execute();
-     * db.table<User>("users").where("name", "like", "%doe%").execute();
-     * db.table<User>("users").where("id", 1).execute();
-     * db.table<User>("users").where({ status: "active", role: "admin" }).execute();
-     * db.table<User>("users").where("age", ">=", 18).where("role", "manager").execute();
-     * db.table<User>("users").where("age", ">=", 18).orWhere((query) => {
-     *  query.where("role", "manager").where("department", "IT");
-     * }).execute();
      */
     where(field: FieldKeys<T>, operator: WhereOperator, value: any): this;
     where(field: FieldKeys<T>, value: any): this;
@@ -339,85 +331,88 @@ declare class QueryBuilder<T extends Record<string, any>> {
     /**
      * Start an OR where group
      */
-    orWhere(callback: (query: QueryBuilder<T>) => void): this;
+    orWhere(callback: (query: QueryBuilder<T, Result>) => void): this;
     /**
      * Start an AND where group
      */
-    andWhere(callback: (query: QueryBuilder<T>) => void): this;
+    andWhere(callback: (query: QueryBuilder<T, Result>) => void): this;
     /**
      * Create a where group with the specified operator
      */
     private whereGroup;
     /**
      * Add a where exists clause using a subquery
-     * @param subqueryBuilder A function that returns a configured query builder for the subquery
-     * @returns The query builder instance
-     * @example
-     * db.table<User>("users")
-     *   .whereExists((subquery) =>
-     *     subquery.table("orders")
-     *       .where("orders.user_id", "=", "users.id")
-     *       .where("total", ">", 1000)
-     *   )
-     *   .execute();
      */
-    whereExists(subqueryBuilder: (qb: DatabaseSDK) => QueryBuilder<any>): this;
+    whereExists(subqueryBuilder: (qb: DatabaseSDK) => QueryBuilder<any, any>): this;
     /**
      * Add a where exists clause with join conditions
-     * @param tableName The table to check for existence
-     * @param leftField The field from the main table
-     * @param rightField The field from the subquery table
-     * @param additionalConditions Additional conditions for the subquery
-     * @returns The query builder instance
-     * @example
-     * db.table<User>("users")
-     *   .whereExistsJoin("orders", "id", "user_id", (qb) =>
-     *     qb.where("total", ">", 1000)
-     *   )
-     *   .execute();
      */
-    whereExistsJoin(tableName: string, leftField: FieldKeys<T>, rightField: string, additionalConditions?: (qb: QueryBuilder<any>) => void): this;
+    whereExistsJoin(tableName: string, leftField: FieldKeys<T>, rightField: string, additionalConditions?: (qb: QueryBuilder<any, any>) => void): this;
     getTableName(): string;
     getParams(): QueryParams<T>;
     /**
      * Group by clause
      */
-    groupBy(...fields: string[]): this;
+    groupBy<K extends keyof T>(...fields: K[]): QueryBuilder<T, Result extends undefined ? Pick<T, K> : Result & Pick<T, K>>;
     /**
      * Having clause for grouped queries
      */
-    having(field: string, operator: WhereOperator, value: any): this;
+    having(field: FieldKeys<T> | string, operator: WhereOperator, value: any): this;
     /**
      * Add an aggregate function
      */
-    aggregate(type: AggregateOptions<T>['type'], field: FieldKeys<T>, alias?: string): this;
+    aggregate<Alias extends string>(type: AggregateOptions<T>['type'], field: FieldKeys<T>, alias?: Alias): QueryBuilder<T, Result extends undefined ? {
+        [P in Alias]: number;
+    } : Result & {
+        [P in Alias]: number;
+    }>;
     /**
      * Shorthand for count aggregate
      */
-    count(field?: FieldKeys<T>, alias?: string): this;
+    count<Alias extends string = 'count'>(field?: FieldKeys<T>, alias?: Alias): QueryBuilder<T, Result extends undefined ? {
+        [P in Alias]: number;
+    } : Result & {
+        [P in Alias]: number;
+    }>;
     /**
      * Shorthand for sum aggregate
      */
-    sum(field: FieldKeys<T>, alias?: string): this;
+    sum<Alias extends string>(field: FieldKeys<T>, alias: Alias): QueryBuilder<T, Result extends undefined ? {
+        [P in Alias]: number;
+    } : Result & {
+        [P in Alias]: number;
+    }>;
     /**
      * Shorthand for average aggregate
      */
-    avg(field: FieldKeys<T>, alias?: string): this;
+    avg<Alias extends string>(field: FieldKeys<T>, alias: Alias): QueryBuilder<T, Result extends undefined ? {
+        [P in Alias]: number;
+    } : Result & {
+        [P in Alias]: number;
+    }>;
     /**
      * Shorthand for minimum aggregate
      */
-    min(field: FieldKeys<T>, alias?: string): this;
+    min<Alias extends string>(field: FieldKeys<T>, alias: Alias): QueryBuilder<T, Result extends undefined ? {
+        [P in Alias]: number;
+    } : Result & {
+        [P in Alias]: number;
+    }>;
     /**
      * Shorthand for maximum aggregate
      */
-    max(field: FieldKeys<T>, alias?: string): this;
+    max<Alias extends string>(field: FieldKeys<T>, alias: Alias): QueryBuilder<T, Result extends undefined ? {
+        [P in Alias]: number;
+    } : Result & {
+        [P in Alias]: number;
+    }>;
     toParams(): Promise<QueryParams<T>>;
     /**
      * Execute with transformations
      * @param axiosConfig Optional axios config to be used for this request
      * @returns Promise with the query results
      */
-    query(axiosConfig?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    query(axiosConfig?: AxiosRequestConfig): Promise<ApiResponse<Result extends undefined ? T : Result>>;
     /**
      * Create a record in the table
      * @param data The data to create
@@ -464,7 +459,7 @@ declare class QueryBuilder<T extends Record<string, any>> {
      *   .select("id", "name", "email")
      *   .execute();
      */
-    select(...fields: string[]): this;
+    select<K extends keyof T>(...fields: K[]): QueryBuilder<T, Result extends undefined ? Pick<T, K> : Result & Pick<T, K>>;
 }
 export {};
 //# sourceMappingURL=client.d.ts.map