@bairock/lenz 0.0.6 → 0.0.8

package/README.md

@@ -6,10 +6,12 @@ GraphQL-based ORM for MongoDB (Prisma style)
 
 - ✅ **GraphQL SDL Schema** - Define models using GraphQL syntax
 - ✅ **TypeScript First** - Full type safety and autocompletion
-- ✅ **MongoDB Native** - Leverage all MongoDB features
+- ✅ **MongoDB Native** - Leverage all MongoDB features including aggregation
 - ✅ **Prisma Style** - Familiar configuration and client generation
 - ✅ **Auto-generated Client** - Generate TypeScript client from GraphQL schema
 - ✅ **Relations Support** - One-to-One, One-to-Many, Many-to-Many
+- ✅ **Smart Loading Strategies** - Automatic choice between populate (separate queries) and lookup (server-side joins)
+- ✅ **Automatic Indexing** - Intelligent index creation for foreign key fields
 - ✅ **Transactions** - ACID transactions with MongoDB
 
 ## Quick Start
@@ -41,8 +43,15 @@ type User @model {
   id: ID! @id
   email: String! @unique
   name: String!
+
+  # One-to-many relationship (auto-selects lookup strategy)
   posts: [Post!]! @relation(field: "postIds")
-  postIds: [ID!]!
+  postIds: [ID!]!  # Array automatically indexed
+
+  # One-to-one relationship (auto-selects populate strategy)
+  profile: Profile @relation(field: "profileId")
+  profileId: ID  # Sparse index automatically created
+
   createdAt: DateTime! @createdAt
   updatedAt: DateTime! @updatedAt
 }
@@ -51,8 +60,28 @@ type Post @model {
   id: ID! @id
   title: String!
   content: String
+
+  # Many-to-one relationship (auto-selects populate strategy)
   author: User! @relation(field: "authorId")
-  authorId: ID!
+  authorId: ID!  # Foreign key index automatically created
+
+  # Many-to-many relationship with ID arrays (auto-selects lookup strategy)
+  categories: [Category!]! @relation(field: "categoryIds")
+  categoryIds: [ID!]!  # Multikey index automatically created
+}
+
+type Profile @model {
+  id: ID! @id
+  bio: String
+  user: User @relation(field: "userId", strategy: "populate")
+  userId: ID
+}
+
+type Category @model {
+  id: ID! @id
+  name: String! @unique
+  posts: [Post!]! @relation(field: "postIds", strategy: "lookup", index: false)
+  postIds: [ID!]!  # No auto-index (index: false)
 }
 ```
 
@@ -72,12 +101,13 @@ import { LenzClient } from '../generated/lenz/client';
 async function main() {
   const lenz = new LenzClient({
     url: process.env.MONGODB_URI,
-    database: 'myapp'
+    database: 'myapp',
+    log: ['query', 'info']  // Enable query logging
   });
 
   await lenz.$connect();
 
-  // Create a user
+  // Create a user with posts (populate strategy for posts)
   const user = await lenz.user.create({
     data: {
       email: 'alice@example.com',
@@ -89,19 +119,95 @@ async function main() {
       }
     },
     include: {
-      posts: true
+      posts: true,      // Uses populate strategy (separate queries)
+      profile: true     // Uses populate strategy (one-to-one)
+    }
+  });
+
+  // Query with include - automatic strategy selection
+  const authorWithBooks = await lenz.author.findUnique({
+    where: { id: 'some-author-id' },
+    include: {
+      books: true       // Uses lookup strategy (one-to-many, single query)
     }
   });
 
-  // Query users
-  const users = await lenz.user.findMany({
+  // Manual array synchronization for lookup strategy
+  // When creating a book, add its ID to author.bookIds
+  const newBook = await lenz.book.create({
+    data: {
+      title: 'New Book',
+      authorId: 'author-id'
+    }
+  });
+
+  // Manually update the author's bookIds array
+  await lenz.author.update({
+    where: { id: 'author-id' },
+    data: {
+      bookIds: {
+        push: newBook.id  // Add new book ID to array
+      }
+    }
+  });
+
+  // Complex query with filtering and sorting
+  const posts = await lenz.post.findMany({
     where: {
-      email: {
-        contains: 'example'
+      title: { contains: 'tutorial' },
+      categories: {
+        some: { name: { equals: 'Programming' } }
       }
+    },
+    orderBy: { createdAt: 'desc' },
+    take: 10,
+    include: {
+      author: true,      // populate strategy
+      categories: true   // many-to-many lookup strategy (server-side join with $lookup)
     }
   });
 
+  // Transaction example (requires replica set)
+  await lenz.$transaction(async (tx) => {
+    const updatedUser = await lenz.user.update({
+      where: { id: user.id },
+      data: { name: 'Alice Updated' }
+    });
+
+    await lenz.post.create({
+      data: {
+        title: 'Transaction Post',
+        authorId: user.id
+      }
+    });
+  });
+
+  // Advanced many-to-many lookup with filtering
+  // Uses MongoDB aggregation pipeline for server-side joins
+  const postsWithTechCategories = await lenz.post.findMany({
+    where: {
+      categories: {
+        some: {
+          name: { equals: 'Technology' }
+        }
+      }
+    },
+    include: {
+      categories: {
+        where: {
+          name: { equals: 'Technology' }
+        }
+      }
+    },
+    orderBy: { createdAt: 'desc' },
+    take: 5
+  });
+
+  // Note: For lookup strategy, array synchronization is manual
+  // When creating relationships, update both arrays:
+  // await lenz.post.update({ where: { id: postId }, data: { categoryIds: { push: categoryId } } });
+  // await lenz.category.update({ where: { id: categoryId }, data: { postIds: { push: postId } } });
+
   await lenz.$disconnect();
 }
 ```
@@ -143,13 +249,35 @@ Lenz extends GraphQL with custom directives:
 - `@unique` - Creates a unique index
 - `@index` - Creates a regular index
 - `@default(value: "...")` - Sets default value
-- `@relation(field: "...")` - Defines relation field (foreign key must be in the same model)
+- `@relation(field: "...", strategy: "populate|lookup", index: true|false)` - Defines relation with loading strategy and index control
 - `@createdAt` - Auto-sets creation timestamp
 - `@updatedAt` - Auto-updates timestamp
+- `@embedded` - Marks a type as embedded document
+- `@hide` - Excludes field from query results by default
 
 ## Relations
 
-Lenz requires explicit foreign key fields for all relation types:
+Lenz implements MongoDB-native relations with explicit foreign key fields and intelligent loading strategies. Each relation type has an optimal default strategy for loading related data (see [Relation Loading Strategies](#relation-loading-strategies) for details).
+
+**Key principles:**
+- Foreign keys must be in the **source model** (the model containing `@relation`)
+- Arrays are automatically initialized for required array fields
+- Indexes are automatically created for foreign key fields (configurable)
+- Loading strategy is automatically selected based on relation type
+
+### Automatic Array Initialization
+
+Required array fields (like `bookIds: [ID!]!`) are automatically initialized with empty arrays `[]` when creating documents. This prevents MongoDB `$in needs an array` errors when querying relations.
+
+```typescript
+// When creating a document, required arrays are automatically set to []
+const author = await lenz.author.create({
+  data: {
+    name: 'John Doe',
+    // bookIds is automatically set to [] even if not provided
+  }
+});
+```
 
 ### One-to-Many / Many-to-One
 A bidirectional relationship where one side has an array and the other has a single reference:
@@ -157,52 +285,203 @@ A bidirectional relationship where one side has an array and the other has a sin
 ```graphql
 type Author @model {
   id: ID! @id
-  books: [Book!]! @relation(field: "bookIds")  # one-to-many side
-  bookIds: [ID!]!                               # array of Book IDs in Author document
+  books: [Book!]! @relation(field: "bookIds")  # one-to-many side, auto: lookup strategy
+  bookIds: [ID!]!                               # array automatically indexed (multikey index)
 }
 
 type Book @model {
   id: ID! @id
-  author: Author! @relation(field: "authorId")  # many-to-one side
-  authorId: ID!                                 # single Author ID in Book document
+  author: Author! @relation(field: "authorId")  # many-to-one side, auto: populate strategy
+  authorId: ID!                                 # single ID automatically indexed (sparse index)
 }
 ```
 
-- **Author → Book (one-to-many):** Foreign key `bookIds` is an array of IDs in the Author document
-- **Book → Author (many-to-one):** Foreign key `authorId` is a single ID in the Book document
+- **Author → Book (one-to-many):** Uses `lookup` strategy by default (server-side join). Requires manual synchronization of `bookIds` array.
+- **Book → Author (many-to-one):** Uses `populate` strategy by default (separate query). Foreign key `authorId` has automatic sparse index.
+- **Indexes:** Multikey index on `bookIds`, sparse index on `authorId` (created automatically).
 
 ### One-to-One (foreign key single ID in source model)
+
 ```graphql
 type User @model {
   id: ID! @id
-  profile: Profile @relation(field: "profileId")
-  profileId: ID
+  profile: Profile @relation(field: "profileId")  # auto: populate strategy
+  profileId: ID                                   # optional, sparse index
 }
 
 type Profile @model {
   id: ID! @id
-  user: User @relation(field: "userId")
-  userId: ID
+  user: User @relation(field: "userId", strategy: "populate")  # explicit populate
+  userId: ID                                   # optional, sparse index
 }
 ```
 
+- **Strategy:** Uses `populate` by default (separate queries for each side)
+- **Indexes:** Sparse indexes on `profileId` and `userId` (optional fields)
+- **Optional:** Both sides can be optional (nullable IDs)
+- **Bidirectional:** Each side maintains its own foreign key
+
 ### Many-to-Many (ID arrays on both sides)
+
 ```graphql
 type Post @model {
   id: ID! @id
-  categories: [Category!]! @relation(field: "categoryIds")
-  categoryIds: [ID!]!
+  categories: [Category!]! @relation(field: "categoryIds")  # auto: lookup strategy (default for arrays)
+  categoryIds: [ID!]!                                        # multikey index
 }
 
 type Category @model {
   id: ID! @id
-  posts: [Post!]! @relation(field: "postIds")
-  postIds: [ID!]!
+  posts: [Post!]! @relation(field: "postIds", strategy: "lookup", index: false)
+  postIds: [ID!]!                                            # no auto-index (index: false)
 }
 ```
 
+- **Strategy:** Uses `lookup` by default when foreign key arrays are specified (server-side joins with MongoDB's `$lookup` aggregation), `populate` for join collections
+- **Indexes:** Multikey indexes on both array fields (configurable with `index: false`)
+- **Bidirectional:** Both sides maintain arrays of IDs
+- **Manual sync:** You must manually synchronize both arrays when creating/updating relations (for `lookup` strategy)
+
+**Example - Manual synchronization for many-to-many lookup strategy:**
+
+```typescript
+// Create a post and category
+const post = await lenz.post.create({
+  data: {
+    title: 'My Post',
+    categoryIds: [] // Initialize empty array
+  }
+});
+
+const category = await lenz.category.create({
+  data: {
+    name: 'Technology',
+    postIds: [] // Initialize empty array
+  }
+});
+
+// Add category to post
+await lenz.post.update({
+  where: { id: post.id },
+  data: {
+    categoryIds: {
+      push: category.id // Add category ID to post's array
+    }
+  }
+});
+
+// Add post to category (bidirectional sync)
+await lenz.category.update({
+  where: { id: category.id },
+  data: {
+    postIds: {
+      push: post.id // Add post ID to category's array
+    }
+  }
+});
+```
+
 **Important:** Foreign keys must always be in the **source model** (the model containing the `@relation` directive). Classic one-to-many patterns with foreign keys in target models will cause validation errors.
 
+## Relation Loading Strategies
+
+Lenz automatically chooses the optimal strategy for loading related data, balancing performance and simplicity. You can also explicitly override the strategy.
+
+### Populate Strategy (Default for oneToOne, manyToOne)
+
+Uses separate queries - first fetches the main document, then queries related collections. Best for simple relationships and sharded environments.
+
+```graphql
+type User @model {
+  profile: Profile @relation(field: "profileId", strategy: "populate")
+  profileId: ID
+}
+```
+
+### Lookup Strategy (Default for oneToMany)
+
+Uses MongoDB's `$lookup` aggregation operator for server-side joins. Best for high-read scenarios with bidirectional relationships.
+
+```graphql
+type Author @model {
+  books: [Book!]! @relation(field: "bookIds", strategy: "lookup")
+  bookIds: [ID!]!
+}
+```
+
+**Note:** When using `lookup` strategy, you must manually synchronize ID arrays (e.g., `bookIds`) when creating/updating/deleting related documents.
+
+**Include options support:** Lookup strategy now supports `where`, `orderBy`, `take`, and `skip` options for filtering, sorting, and paginating related documents.
+
+Example:
+```typescript
+const author = await lenz.author.findUnique({
+  where: { id: 'author-id' },
+  include: {
+    books: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      take: 5
+    }
+  }
+});
+```
+
+### Automatic Strategy Selection
+
+| Relation Type | Default Strategy | Reason |
+|--------------|------------------|--------|
+| `oneToOne` | `populate` | Simple relationships, no arrays |
+| `manyToOne` | `populate` | Single reference, no arrays |
+| `oneToMany` | `lookup` | Array of IDs in source document (e.g., Author.bookIds) |
+| `manyToMany` | `lookup` (if foreign key array specified) or `populate` (if join collection) | Foreign key arrays use server-side joins, join collections use separate queries |
+
+**Note:** The lookup strategy now supports include options (where, orderBy, take, skip) for both array foreign keys and single foreign key relations. However, nested includes are not yet supported for lookup strategy but are fully supported for populate strategy.
+
+**Many-to-Many Lookup Strategy:**
+
+When a many-to-many relationship uses foreign key arrays (either single-sided or both sides), Lenz automatically uses the `lookup` strategy with MongoDB's `$lookup` aggregation operator. This performs server-side joins for optimal read performance. For example, `post.categoryIds` array referencing categories.
+
+```graphql
+type Post @model {
+  categories: [Category!]! @relation(field: "categoryIds", strategy: "lookup")
+  categoryIds: [ID!]!  # multikey index automatically created
+}
+
+type Category @model {
+  posts: [Post!]! @relation(field: "postIds", strategy: "lookup", index: false)
+  postIds: [ID!]!  # no auto-index (index: false)
+}
+```
+
+**Many-to-Many Populate Strategy:**
+
+When a many-to-many relationship uses a join collection (no foreign key arrays), Lenz uses the `populate` strategy with separate queries.
+
+```graphql
+type Post @model {
+  categories: [Category!]! @relation  # no field parameter → join collection
+}
+
+type Category @model {
+  posts: [Post!]! @relation
+}
+```
+
+### Automatic Indexing
+
+Lenz automatically creates indexes for foreign key fields when `index: true` (default). You can disable this:
+
+```graphql
+type Author @model {
+  books: [Book!]! @relation(field: "bookIds", index: false)
+  bookIds: [ID!]!
+}
+```
+
+- For arrays (oneToMany): Creates multikey indexes
+- For single IDs (oneToOne, manyToOne): Creates sparse indexes
+
 ## Supported Field Types
 
 - `String`
@@ -215,6 +494,78 @@ type Category @model {
 - `Json` (any JSON value)
 - `ObjectId` (MongoDB ObjectId as string)
 
+## Best Practices with MongoDB
+
+### 1. Schema Design
+- **Embed documents** when data is accessed together frequently (use `@embedded` directive)
+- **Reference documents** when data is large or accessed independently
+- **Use arrays judiciously** - large arrays can impact performance
+- **Denormalize carefully** - duplicate data for read performance, but maintain consistency
+
+### 2. Index Strategy
+- **Auto-index foreign keys** - Lenz does this by default with `index: true`
+- **Add compound indexes** for frequently queried field combinations
+- **Use sparse indexes** for optional fields (auto-created for optional relations)
+- **Monitor index usage** with `$indexStats`
+
+### 3. Performance Optimization
+- **Use `lookup` strategy** for high-read bidirectional relationships
+- **Use `populate` strategy** for simple relationships and sharded clusters
+- **Batch operations** with `createMany`, `updateMany` instead of individual calls
+- **Project only needed fields** with `select` option
+
+### 4. Query Patterns
+- **Filter early** - push filters to database with `where` clauses
+- **Avoid large skip/limit** - use cursor-based pagination (`cursor` option)
+- **Use transactions** for multi-document consistency (requires replica set)
+- **Monitor slow queries** with MongoDB profiler
+
+### 5. Data Consistency
+- **Manual array sync** - when using `lookup` strategy, maintain ID arrays
+- **Use default values** for required fields to avoid validation errors
+- **Handle race conditions** with optimistic concurrency or transactions
+- **Implement soft deletes** with `deletedAt` field instead of hard deletes
+
+### 6. Many-to-Many Performance Optimization
+- **Array size limits:** Keep array sizes reasonable (<1000 elements). Large arrays increase `$lookup` complexity and memory usage.
+- **Batch synchronization:** When updating multiple relationships, batch array operations to reduce database round trips.
+- **Index management:** Regularly monitor and optimize multikey indexes for array fields.
+- **Alternative approaches:** For extremely large many-to-many relationships, consider:
+  - **Denormalization:** Embed frequently accessed data
+  - **Hybrid approach:** Use `lookup` for recent/active relationships, `populate` for historical
+  - **Materialized views:** Pre-compute relationships for read-heavy scenarios
+
+### 7. When to Use Each Strategy
+
+#### Use **Populate** when:
+- Simple one-to-one or many-to-one relationships
+- Working with sharded clusters (`$lookup` doesn't work across shards)
+- Relationships are rarely accessed
+- You prefer automatic data consistency
+- Many-to-many relationships with join collections (no foreign key arrays)
+- Small datasets where separate queries are acceptable
+
+#### Use **Lookup** when:
+- High-read scenarios with one-to-many or many-to-many relationships
+- Need server-side joins for complex filtering/sorting
+- Willing to manually maintain ID arrays
+- Maximum read performance is critical
+- Many-to-many relationships with foreign key arrays (both sides)
+- Medium to large datasets where join performance matters
+
+#### Special Considerations for Many-to-Many Lookup:
+- **Array size:** Large arrays (>1000 IDs) can impact `$lookup` performance. Consider denormalization or hybrid approaches.
+- **Indexing:** Multikey indexes are essential for array fields. Monitor index size and performance.
+- **Consistency:** Manual array synchronization requires careful application logic to maintain data integrity.
+- **Sharding:** `$lookup` doesn't work across shards. For sharded clusters, use `populate` strategy or ensure related documents are on the same shard.
+
+### 8. Production Readiness
+- **Enable replica set** for transaction support
+- **Set up proper connection pooling** in `lenz.config.ts`
+- **Implement retry logic** for transient failures
+- **Use environment-specific configurations**
+- **Monitor connection health** with regular `ping` commands
+
 ## CLI Commands
 
 ```bash

package/dist/engine/CodeGenerator.d.ts

@@ -31,6 +31,7 @@ export declare class CodeGenerator {
     private generateModelDelegate;
     private generateRelationInclusionCode;
     private toCamelCase;
+    private toCollectionName;
 }
 export interface GeneratedFiles {
     [filePath: string]: string;

package/dist/engine/CodeGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeGenerator.d.ts","sourceRoot":"","sources":["../../src/engine/CodeGenerator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG3E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAUb;IAEF,OAAO,CAAC,6BAA6B;IAyBrC,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,sBAAsB;IA8B9B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,wBAAwB;IA4IhC,OAAO,CAAC,oBAAoB;IAM5B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc;IAmClD,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,cAAc;IAwLtB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,aAAa;IAiKrB,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,yBAAyB;IA4LjC,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,oBAAoB;IA2N5B,OAAO,CAAC,wBAAwB;IAiEhC,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,qBAAqB;IA6a7B,OAAO,CAAC,6BAA6B;IA8DrC,OAAO,CAAC,WAAW;CAGpB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"CodeGenerator.d.ts","sourceRoot":"","sources":["../../src/engine/CodeGenerator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG3E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAUb;IAEF,OAAO,CAAC,6BAA6B;IAyBrC,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,sBAAsB;IA8B9B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,wBAAwB;IA4IhC,OAAO,CAAC,oBAAoB;IAM5B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc;IAmClD,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,cAAc;IAwLtB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,aAAa;IAiKrB,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,yBAAyB;IA4LjC,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,oBAAoB;IA0Q5B,OAAO,CAAC,wBAAwB;IAiEhC,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,qBAAqB;IAqb7B,OAAO,CAAC,6BAA6B;IAuOrC,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,gBAAgB;CAGzB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B"}