add relationship support and try to solve some of the ts errors.

Author: dustintownsend

packages/mizzle-orm/examples/crud-operations.ts

@@ -4,6 +4,7 @@
 
 import {
   createMongoOrm,
+  defineCollections,
   mongoCollection,
   objectId,
   publicId,
@@ -12,7 +13,6 @@ import {
   date,
   array,
 } from '../src/index';
-import type { InferDocument, InferInsert } from '../src/index';
 
 // Define collections
 const users = mongoCollection(
@@ -85,9 +85,6 @@ const projects = mongoCollection(
   },
 );
 
-// Types
-type User = InferDocument<typeof users>;
-type NewUser = InferInsert<typeof users>;
 
 /**
  * Example usage
@@ -97,10 +94,11 @@ async function main() {
   const MONGO_URI = process.env.MONGO_URI || 'mongodb://localhost:27017';
 
   // Create ORM instance
+  const collections = defineCollections({ users, projects });
   const orm = await createMongoOrm({
     uri: MONGO_URI,
     dbName: 'mizzle_example',
-    collections: [users, projects],
+    collections,
   });
 
   console.log('✓ Connected to MongoDB');
@@ -121,14 +119,14 @@ async function main() {
   // ========== CREATE ==========
   console.log('\n--- CREATE ---');
 
-  const newUser: NewUser = {
+  const alice = await db.users.create({
+    // TypeScript note: id, _id, createdAt, updatedAt, deletedAt, isActive, role
+    // are automatically generated or have defaults, so they're optional here
     orgId: ctx.tenantIdObjectId!,
     email: 'alice@example.com',
     displayName: 'Alice Smith',
     tags: ['developer', 'typescript'],
-  };
-
-  const alice = await db.users.create(newUser);
+  });
   console.log('Created user:', alice.id, alice.email);
 
   const bob = await db.users.create({
@@ -173,7 +171,10 @@ async function main() {
     tags: ['developer', 'typescript', 'mongodb'],
   });
   console.log('Updated user:', updatedAlice?.displayName);
-  console.log('Updated timestamp changed:', updatedAlice?.updatedAt > alice.updatedAt);
+  console.log(
+    'Updated timestamp changed:',
+    updatedAlice?.updatedAt && updatedAlice.updatedAt > alice.updatedAt
+  );
 
   // Update many
   const updated = await db.users.updateMany({ role: 'user' }, { isActive: true });

packages/mizzle-orm/examples/relations.ts

@@ -0,0 +1,222 @@
+/**
+ * Relations example - REFERENCE, LOOKUP, and EMBED
+ */
+
+import {
+  mongoCollection,
+  objectId,
+  string,
+  number,
+  date,
+  createMongoOrm,
+} from '../src/index';
+
+// ============ COLLECTIONS ============
+
+// Organizations
+const organizations = mongoCollection('organizations', {
+  name: string(),
+  createdAt: date().defaultNow(),
+});
+
+// Users with REFERENCE to organizations
+const users = mongoCollection(
+  'users',
+  {
+    email: string().email(),
+    name: string(),
+    orgId: objectId(), // Foreign key to organizations
+    createdAt: date().defaultNow(),
+  },
+  {
+    relations: (r) => ({
+      // REFERENCE: Validates that orgId points to existing organization
+      organization: r.reference(organizations, {
+        localField: 'orgId',
+        foreignField: '_id',
+      }),
+      // LOOKUP: Populates organization data
+      organizationData: r.lookup(organizations, {
+        localField: 'orgId',
+        foreignField: '_id',
+        one: true, // Single document
+      }),
+    }),
+  }
+);
+
+// Posts with REFERENCE and LOOKUP to users
+const posts = mongoCollection(
+  'posts',
+  {
+    title: string(),
+    content: string(),
+    authorId: objectId(), // Foreign key to users
+    likes: number().default(0),
+    createdAt: date().defaultNow(),
+  },
+  {
+    relations: (r) => ({
+      // REFERENCE: Validates authorId exists
+      author: r.reference(users, {
+        localField: 'authorId',
+        foreignField: '_id',
+      }),
+      // LOOKUP: Populates author data
+      authorData: r.lookup(users, {
+        localField: 'authorId',
+        foreignField: '_id',
+        one: true,
+      }),
+    }),
+  }
+);
+
+// Comments with nested LOOKUP
+const comments = mongoCollection(
+  'comments',
+  {
+    postId: objectId(),
+    authorId: objectId(),
+    content: string(),
+    createdAt: date().defaultNow(),
+  },
+  {
+    relations: (r) => ({
+      post: r.lookup(posts, {
+        localField: 'postId',
+        foreignField: '_id',
+        one: true,
+      }),
+      author: r.lookup(users, {
+        localField: 'authorId',
+        foreignField: '_id',
+        one: true,
+      }),
+    }),
+  }
+);
+
+// ============ USAGE EXAMPLE ============
+
+async function relationsExample() {
+  // Connect to MongoDB
+  const orm = await createMongoOrm({
+    uri: process.env.MONGO_URI || 'mongodb://localhost:27017',
+    dbName: 'mizzle_relations_example',
+    collections: { organizations, users, posts, comments },
+  });
+
+  const ctx = orm.createContext({});
+  const db = orm.withContext(ctx);
+
+  try {
+    // Note: Using `as any` type assertions to work around TypeScript's
+    // complexity with union types in multi-collection ORMs.
+    // The code is fully type-safe at runtime.
+
+    // 1. REFERENCE VALIDATION
+    console.log('\n=== REFERENCE Validation ===');
+
+    // Create an organization
+    const org = await db.organizations.create({
+      name: 'Acme Corp',
+    });
+    console.log('Created org:', org.name);
+
+    // Create a user with valid orgId (REFERENCE validates this)
+    const user = await db.users.create({
+      email: 'alice@acme.com',
+      name: 'Alice',
+      orgId: org._id, // Must reference existing organization
+    });
+    console.log('Created user:', user.name);
+
+    // Try to create user with invalid orgId - will throw error
+    try {
+      const { ObjectId } = await import('mongodb');
+      await db.users.create({
+        email: 'invalid@example.com',
+        name: 'Invalid User',
+        orgId: new ObjectId(), // Non-existent org
+      });
+    } catch (err) {
+      console.log('✓ Reference validation caught invalid orgId');
+    }
+
+    // 2. LOOKUP POPULATION
+    console.log('\n=== LOOKUP Population ===');
+
+    // Create a post
+    const post = await db.posts.create({
+      title: 'My First Post',
+      content: 'Hello, World!',
+      authorId: user._id,
+    });
+
+    // Fetch post and populate author
+    const foundPosts = await db.posts.findMany({ _id: post._id });
+    const postsWithAuthor = await db.posts.populate(foundPosts, 'authorData');
+
+    console.log('Post:', postsWithAuthor[0].title);
+    console.log('Author:', postsWithAuthor[0].authorData.name);
+    console.log('Author Email:', postsWithAuthor[0].authorData.email);
+
+    // 3. MULTIPLE POPULATIONS
+    console.log('\n=== Multiple Populations ===');
+
+    // Create some comments
+    await db.comments.create({
+      postId: post._id,
+      authorId: user._id,
+      content: 'Great post!',
+    });
+
+    // Fetch comments and populate both post and author
+    const foundComments = await db.comments.findMany({});
+    const populatedComments = await db.comments.populate(foundComments, [
+      'post',
+      'author',
+    ]);
+
+    console.log('Comment:', populatedComments[0].content);
+    console.log('On post:', populatedComments[0].post?.title);
+    console.log('By:', populatedComments[0].author?.name);
+
+    // 4. NESTED POPULATION (manually)
+    console.log('\n=== Nested Population ===');
+
+    // Get posts with authors
+    const allPosts = await db.posts.findMany({});
+    const postsWithAuthors = await db.posts.populate(allPosts, 'authorData');
+
+    // For each author, populate their organization
+    for (const postWithAuthor of postsWithAuthors) {
+      const author = postWithAuthor.authorData;
+      if (author) {
+        const usersArray = [author];
+        const usersWithOrg = await db.users.populate(usersArray, 'organizationData');
+        postWithAuthor.authorData = usersWithOrg[0];
+      }
+    }
+
+    console.log('Post:', postsWithAuthors[0].title);
+    console.log('Author:', postsWithAuthors[0].authorData?.name);
+    console.log('Org:', postsWithAuthors[0].authorData?.organizationData?.name);
+  } finally {
+    await orm.close();
+  }
+}
+
+// Run example if called directly
+if (require.main === module) {
+  relationsExample()
+    .then(() => {
+      console.log('\n✓ Relations example completed!');
+      process.exit(0);
+    })
+    .catch((err) => {
+      console.error('Error:', err);
+      process.exit(1);
+    });
+}

packages/mizzle-orm/src/index.ts

@@ -4,7 +4,7 @@
  */
 
 // Core exports
-export { createMongoOrm } from './orm/orm';
+export { createMongoOrm, defineCollections } from './orm/orm';
 export { mongoCollection } from './collection/collection';
 
 // Field factory functions

packages/mizzle-orm/src/orm/orm.ts

@@ -9,6 +9,26 @@ import { ObjectId } from 'mongodb';
 import { nanoid } from 'nanoid';
 import { CollectionFacade } from '../query/collection-facade';
 
+/**
+ * Helper function to create properly typed collections object.
+ * This preserves exact types for perfect type inference.
+ *
+ * @example
+ * ```ts
+ * const collections = defineCollections({ users, posts });
+ * const orm = await createMongoOrm({
+ *   uri: process.env.MONGO_URI!,
+ *   dbName: 'myapp',
+ *   collections,
+ * });
+ * ```
+ */
+export function defineCollections<T extends Record<string, CollectionDefinition<any>>>(
+  collections: T,
+): T {
+  return collections;
+}
+
 /**
  * Create a Mizzle ORM instance
  *
@@ -28,27 +48,24 @@ import { CollectionFacade } from '../query/collection-facade';
  * const user = await db.users.findOne({ email: 'alice@example.com' });
  * ```
  */
-export async function createMongoOrm<TCollections extends CollectionDefinition[]>(
-  config: OrmConfig & { collections: TCollections },
-): Promise<MongoOrm<CollectionsToRecord<TCollections>>> {
+export async function createMongoOrm<TCollections extends Record<string, CollectionDefinition<any>>>(
+  config: OrmConfig<TCollections>,
+): Promise<MongoOrm<TCollections>> {
   // Connect to MongoDB
   const client = new MongoClient(config.uri, config.clientOptions);
   await client.connect();
 
   // Get database instance
   const db = client.db(config.dbName);
 
-  // Build collection registry
+  // Build collection registry from the collections object
   const collectionRegistry = new Map<string, CollectionDefinition>();
-  for (const collectionDef of config.collections) {
+  for (const [_, collectionDef] of Object.entries(config.collections)) {
     collectionRegistry.set(collectionDef._meta.name, collectionDef);
   }
 
-  // Build collections object for type-safe access
-  const collections = {} as CollectionsToRecord<TCollections>;
-  for (const collectionDef of config.collections) {
-    (collections as any)[collectionDef._meta.name] = collectionDef;
-  }
+  // Collections are already in the right format
+  const collections = config.collections;
 
   /**
    * Create a context object
@@ -81,7 +98,7 @@ export async function createMongoOrm<TCollections extends CollectionDefinition[]
   /**
    * Get a context-bound database facade
    */
-  function withContext(ctx: OrmContext): DbFacade<CollectionsToRecord<TCollections>> {
+  function withContext(ctx: OrmContext): DbFacade<TCollections> {
     // Create a proxy that dynamically creates collection facades
     return new Proxy({} as any, {
       get(_target, collectionName: string) {
@@ -93,7 +110,7 @@ export async function createMongoOrm<TCollections extends CollectionDefinition[]
         // Create and return a CollectionFacade for this collection
         return new CollectionFacade(db, collectionDef, ctx);
       },
-    }) as DbFacade<CollectionsToRecord<TCollections>>;
+    }) as DbFacade<TCollections>;
   }
 
   /**
@@ -138,9 +155,3 @@ export async function createMongoOrm<TCollections extends CollectionDefinition[]
   };
 }
 
-/**
- * Helper type to convert array of collection definitions to a record
- */
-type CollectionsToRecord<T extends CollectionDefinition[]> = {
-  [K in T[number]['_meta']['name']]: Extract<T[number], { _meta: { name: K } }>;
-};