feat(mongo-orm): codec-aware where(), typed field mutations, 1:N tests (FL-04/06/08)

docs/planning/mongo-target/next-steps.md

@@ -65,7 +65,7 @@ Full details in [projects/mongo-example-apps/framework-limitations.md](../../../
 | FL-03 | Timestamp codec type incompatible with `Date`/`string` | Type ergonomics |
 | FL-04 | No typed `$push`/`$pull`/`$inc` | ORM mutations |
 | FL-05 | Pipeline/raw results untyped | Query results |
-| FL-06 | ObjectId filter requires manual `MongoParamRef` wrapping | ORM queries |
+| FL-06 | `where()` does not encode filter values through codecs | ORM queries |
 | FL-07 | No `$vectorSearch` in pipeline builder | Extension (deferred) |
 | FL-08 | 1:N back-relation loading not available/tested | ORM queries |
 | FL-09 | Migration planner creates separate collections for variants | Migration bugs |
@@ -110,10 +110,10 @@ Full details in [projects/mongo-example-apps/framework-limitations.md](../../../
 **Scope**:
 
 - **FL-04**: Implement dot-path field accessor mutations — `$push`, `$pull`, `$inc`, `$set` on nested paths via `u("field.path")` (deferred Phase 1.5 M4). Maps to [ADR 180](../../architecture%20docs/adrs/ADR%20180%20-%20Dot-path%20field%20accessor.md).
-- **FL-06**: ORM `where()` should auto-encode ObjectId-typed fields. When a contract field has `codecId: 'mongo/objectId@1'`, the ORM should wrap the value in `MongoParamRef` automatically instead of requiring the user to construct it manually.
+- **FL-06**: ORM `where()` should encode filter values through codecs, the same way mutations already do. When a contract field has a `codecId`, the ORM should wrap the value in `MongoParamRef` with that codec automatically. Most visible with ObjectId (string → BSON ObjectId), but applies to any codec with a non-identity `encode`.
 - **FL-08**: Validate and test 1:N back-relation loading via `include()`. If it works, add test coverage. If it doesn't, implement it.
 
-**Proof**: The retail store's `mongoRaw` calls for cart add/remove and order status update are replaced with ORM `update()` calls. ObjectId filter helpers (`objectIdEq()`) are removed.
+**Proof**: The retail store's `mongoRaw` calls for cart add/remove and order status update are replaced with ORM `update()` calls. Manual filter helpers (`objectIdEq()`, `rawObjectIdFilter()`) are removed — `where({ userId })` encodes values through codecs automatically.
 
 **Depends on**: Area 1 (type fixes reduce noise, but not a hard blocker).
 

examples/retail-store/src/data/carts.ts

@@ -1,64 +1,32 @@
+import type { CartItemInput } from '../contract';
 import type { Db } from '../db';
-import { executeRaw } from './execute-raw';
-import { objectIdEq, rawObjectIdFilter } from './object-id-filter';
 
 export function getCartByUserId(db: Db, userId: string) {
-  return db.orm.carts.where(objectIdEq('userId', userId)).first();
+  return db.orm.carts.where({ userId }).first();
 }
 
 export function getCartWithUser(db: Db, userId: string) {
-  return db.orm.carts.include('user').where(objectIdEq('userId', userId)).first();
+  return db.orm.carts.include('user').where({ userId }).first();
 }
 
-export function upsertCart(
-  db: Db,
-  userId: string,
-  items: ReadonlyArray<{
-    productId: string;
-    name: string;
-    brand: string;
-    amount: number;
-    price: { amount: number; currency: string };
-    image: { url: string };
-  }>,
-) {
-  return db.orm.carts.where(objectIdEq('userId', userId)).upsert({
+export function upsertCart(db: Db, userId: string, items: ReadonlyArray<CartItemInput>) {
+  return db.orm.carts.where({ userId }).upsert({
     create: { userId, items: [...items] },
     update: { items: [...items] },
   });
 }
 
 export function clearCart(db: Db, userId: string) {
-  return db.orm.carts.where(objectIdEq('userId', userId)).update({ items: [] });
+  return db.orm.carts.where({ userId }).update({ items: [] });
 }
 
-export async function addToCart(
-  db: Db,
-  userId: string,
-  item: {
-    productId: string;
-    name: string;
-    brand: string;
-    amount: number;
-    price: { amount: number; currency: string };
-    image: { url: string };
-  },
-) {
-  const plan = db.raw
-    .collection('carts')
-    .findOneAndUpdate(
-      rawObjectIdFilter('userId', userId),
-      { $push: { items: item }, $setOnInsert: rawObjectIdFilter('userId', userId) },
-      { upsert: true },
-    )
-    .build();
-  await executeRaw(db, plan);
+export function addToCart(db: Db, userId: string, item: CartItemInput) {
+  return db.orm.carts.where({ userId }).upsert({
+    create: { userId, items: [item] },
+    update: (u) => [u.items.push(item)],
+  });
 }
 
-export async function removeFromCart(db: Db, userId: string, productId: string) {
-  const plan = db.raw
-    .collection('carts')
-    .updateOne(rawObjectIdFilter('userId', userId), { $pull: { items: { productId } } })
-    .build();
-  await executeRaw(db, plan);
+export function removeFromCart(db: Db, userId: string, productId: string) {
+  return db.orm.carts.where({ userId }).update((u) => [u.items.pull({ productId })]);
 }

examples/retail-store/src/data/events.ts

@@ -1,19 +1,14 @@
 import { acc } from '@prisma-next/mongo-pipeline-builder';
 import { MongoFieldFilter } from '@prisma-next/mongo-query-ast/execution';
+import type { FieldInputTypes } from '../contract';
 import type { Db } from '../db';
 import { collectResults } from './execute-raw';
 
+type EventBase = Omit<FieldInputTypes['Event'], '_id' | 'type'>;
+
 export function createViewProductEvent(
   db: Db,
-  event: {
-    userId: string;
-    sessionId: string;
-    timestamp: Date;
-    productId: string;
-    subCategory: string;
-    brand: string;
-    exitMethod?: string | null;
-  },
+  event: EventBase & FieldInputTypes['ViewProductEvent'],
 ) {
   return db.orm.events.variant('ViewProductEvent').create({
     userId: event.userId,
@@ -22,19 +17,11 @@ export function createViewProductEvent(
     productId: event.productId,
     subCategory: event.subCategory,
     brand: event.brand,
-    exitMethod: event.exitMethod ?? null,
+    exitMethod: event.exitMethod,
   });
 }
 
-export function createSearchEvent(
-  db: Db,
-  event: {
-    userId: string;
-    sessionId: string;
-    timestamp: Date;
-    query: string;
-  },
-) {
+export function createSearchEvent(db: Db, event: EventBase & FieldInputTypes['SearchEvent']) {
   return db.orm.events.variant('SearchEvent').create({
     userId: event.userId,
     sessionId: event.sessionId,
@@ -43,16 +30,7 @@ export function createSearchEvent(
   });
 }
 
-export function createAddToCartEvent(
-  db: Db,
-  event: {
-    userId: string;
-    sessionId: string;
-    timestamp: Date;
-    productId: string;
-    brand: string;
-  },
-) {
+export function createAddToCartEvent(db: Db, event: EventBase & FieldInputTypes['AddToCartEvent']) {
   return db.orm.events.variant('AddToCartEvent').create({
     userId: event.userId,
     sessionId: event.sessionId,

examples/retail-store/src/data/invoices.ts

@@ -1,24 +1,19 @@
+import type { InvoiceLineItemInput } from '../contract';
 import type { Db } from '../db';
-import { objectIdEq } from './object-id-filter';
 
 export function findInvoiceById(db: Db, id: string) {
-  return db.orm.invoices.where(objectIdEq('_id', id)).first();
+  return db.orm.invoices.where({ _id: id }).first();
 }
 
 export function findInvoiceWithOrder(db: Db, id: string) {
-  return db.orm.invoices.include('order').where(objectIdEq('_id', id)).first();
+  return db.orm.invoices.include('order').where({ _id: id }).first();
 }
 
 export function createInvoice(
   db: Db,
   invoice: {
     orderId: string;
-    items: ReadonlyArray<{
-      name: string;
-      amount: number;
-      unitPrice: number;
-      lineTotal: number;
-    }>;
+    items: ReadonlyArray<InvoiceLineItemInput>;
     subtotal: number;
     tax: number;
     total: number;

examples/retail-store/src/data/orders.ts

@@ -1,34 +1,26 @@
+import type { OrderLineItemInput, StatusEntryInput } from '../contract';
 import type { Db } from '../db';
-import { collectFirstResult } from './execute-raw';
-import { objectIdEq, rawObjectIdFilter } from './object-id-filter';
 
 export function getUserOrders(db: Db, userId: string) {
-  return db.orm.orders.where(objectIdEq('userId', userId)).all();
+  return db.orm.orders.where({ userId }).all();
 }
 
 export function getOrderById(db: Db, id: string) {
-  return db.orm.orders.where(objectIdEq('_id', id)).first();
+  return db.orm.orders.where({ _id: id }).first();
 }
 
 export function getOrderWithUser(db: Db, id: string) {
-  return db.orm.orders.include('user').where(objectIdEq('_id', id)).first();
+  return db.orm.orders.include('user').where({ _id: id }).first();
 }
 
 export function createOrder(
   db: Db,
   order: {
     userId: string;
-    items: ReadonlyArray<{
-      productId: string;
-      name: string;
-      brand: string;
-      amount: number;
-      price: { amount: number; currency: string };
-      image: { url: string };
-    }>;
+    items: ReadonlyArray<OrderLineItemInput>;
     shippingAddress: string;
     type: string;
-    statusHistory: ReadonlyArray<{ status: string; timestamp: Date }>;
+    statusHistory: ReadonlyArray<StatusEntryInput>;
   },
 ) {
   return db.orm.orders.create({
@@ -41,17 +33,9 @@ export function createOrder(
 }
 
 export function deleteOrder(db: Db, id: string) {
-  return db.orm.orders.where(objectIdEq('_id', id)).delete();
+  return db.orm.orders.where({ _id: id }).delete();
 }
 
-export async function updateOrderStatus(
-  db: Db,
-  orderId: string,
-  entry: { status: string; timestamp: Date },
-) {
-  const plan = db.raw
-    .collection('orders')
-    .findOneAndUpdate(rawObjectIdFilter('_id', orderId), { $push: { statusHistory: entry } })
-    .build();
-  return collectFirstResult<Record<string, unknown>>(db, plan);
+export function updateOrderStatus(db: Db, orderId: string, entry: StatusEntryInput) {
+  return db.orm.orders.where({ _id: orderId }).update((u) => [u.statusHistory.push(entry)]);
 }

examples/retail-store/src/data/products.ts

@@ -3,7 +3,6 @@ import { MongoParamRef } from '@prisma-next/mongo-value';
 import type { FieldOutputTypes } from '../contract';
 import type { Db } from '../db';
 import { collectResults } from './execute-raw';
-import { objectIdEq } from './object-id-filter';
 
 type Product = FieldOutputTypes['Product'];
 
@@ -21,7 +20,7 @@ export async function findProductsPaginated(
 }
 
 export function findProductById(db: Db, id: string) {
-  return db.orm.products.where(objectIdEq('_id', id)).first();
+  return db.orm.products.where({ _id: id }).first();
 }
 
 function escapeRegex(str: string) {

examples/retail-store/src/data/users.ts

@@ -1,14 +1,14 @@
+import type { FieldInputTypes } from '../contract';
 import type { Db } from '../db';
-import { objectIdEq } from './object-id-filter';
 
 export function findUsers(db: Db) {
   return db.orm.users.all();
 }
 
 export function findUserById(db: Db, id: string) {
-  return db.orm.users.where(objectIdEq('_id', id)).first();
+  return db.orm.users.where({ _id: id }).first();
 }
 
-export function createUser(db: Db, data: { name: string; email: string; address: null }) {
+export function createUser(db: Db, data: Omit<FieldInputTypes['User'], '_id'>) {
   return db.orm.users.create(data);
 }

examples/retail-store/src/seed.ts

@@ -366,6 +366,7 @@ export async function seed(db: Db) {
     productId: p0._id,
     subCategory: 'Topwear',
     brand: 'Heritage',
+    exitMethod: null,
   });
 
   await createAddToCartEvent(db, {

examples/retail-store/test/aggregation.test.ts

@@ -21,6 +21,7 @@ describe('aggregation pipelines', { timeout: timeouts.spinUpMongoMemoryServer },
         productId: `prod-${i}`,
         subCategory: 'Topwear',
         brand: 'TestBrand',
+        exitMethod: null,
       });
     }
     for (let i = 0; i < 2; i++) {

examples/retail-store/test/crud-lifecycle.test.ts

@@ -243,6 +243,7 @@ describe('CRUD lifecycle', { timeout: timeouts.spinUpMongoMemoryServer }, () =>
       productId: 'prod-1',
       subCategory: 'Topwear',
       brand: 'TestBrand',
+      exitMethod: null,
     });
 
     const events = await findEventsByUser(ctx.db, 'user-1');

examples/retail-store/test/order-lifecycle.test.ts

@@ -80,7 +80,7 @@ describe('order lifecycle (integration)', { timeout: timeouts.spinUpMongoMemoryS
     expect(delivered).not.toBeNull();
     expect(delivered!['statusHistory']).toHaveLength(3);
 
-    const statuses = (delivered!['statusHistory'] as Array<{ status: string }>).map(
+    const statuses = (delivered!['statusHistory'] as ReadonlyArray<{ status: string }>).map(
       (s) => s.status,
     );
     expect(statuses).toEqual(['placed', 'shipped', 'delivered']);