We already have a connection and models. Time to move data. CRUD is the set of four operations that hold up any stateful application: create, read, update and delete. With Mongoose each one can be written in several ways, and they are not all equivalent: some validate and some do not, some return the previous document and some the new one, some execute the query and some merely build it.

This lesson walks through all four with their real traps, translates Mongoose errors into the Module 6 hierarchy, and culminates in the moment announced back in the module's first lesson: src/catalog-data.js retires and src/repositories/events.js takes its place with the same public signature, without the controllers or the domain noticing.

1. Creating documents
2. Duplicate key errors and the Module 6 hierarchy
3. Reading: lazy Query objects, projections and lean()
4. Sorting, limiting and paginating
5. Essential query operators
6. Updating: runValidators, $set, $inc
7. Deleting and soft deletes
8. The repository: retiring catalog-data.js
9. POST /orders against the database
10. Mongoose errors and their HTTP status

There are two routes, and the difference is not cosmetic.

save() and create() return the already persisted document, with its _id, its timestamps and its virtuals. insertMany is far faster than a loop of create calls, but by default it is ordered: if the third document fails, the first two are already written and the rest are never attempted; with { ordered: false } it attempts them all and reports the failures, which is what you will want in a seed. Which to use: new + save() lets you apply logic between building and writing (computing the total, generating codes); create() is more direct when the data already arrives complete.

eventId and code have unique indexes. If you insert a duplicate, MongoDB answers with E11000 duplicate key error. If you do not translate it, the Module 6 handler will treat it as a bug and return a 500. But it is not a bug: it is an operational state conflict, and it deserves a 409.

Notice where this translation lives: in the repository layer, not in the controller. It is consistent with the architecture of lesson 07-01: the controller must not know MongoDB exists, and therefore must not know what an E11000 is either. The repository translates from the engine's language into the application's.

Here is the surprise that throws almost everyone the first time:

Being lazy is an advantage: you can build the query in pieces according to the optional filters arriving in the query string and run it at the end. The trap is that a query without await does nothing and raises no error. Rule: always await, or .exec(), which returns a real promise and improves stack traces.

None of them throws when nothing is found: they return null or [], and turning that null into a ResourceNotFound is the job of the repository or the controller. With .orFail() it throws instead of returning null, which is sometimes more convenient.

Projection: asking only for the fields you need. Fewer bytes, less memory, less work for the engine.

That last example matters: the catalog landing page does not need the 7 sessions with their capacity and price, only the title and the venue.

lean() returns plain JavaScript objects instead of Mongoose documents. By default, Mongoose wraps every result in an instance with change tracking, getters, virtuals and methods: building it is expensive. A lean object has no save(), no virtuals and no getter conversion — you get the raw BSON types — but it is built almost for free.

The rule: use lean() on every read that ends in res.json(); do not use it when you are going to modify the document. On large listings the difference is several times over in both time and memory. In Escena Viva there is a nuance: our repository returns domain objects, so it will call lean() and then Event.fromJSON(...), which is cheaper than hydrating twice.

For the first pages it is perfect. But skip degrades linearly: to serve page 5,000 the engine locates and discards 100,000 documents before it starts returning anything; it does not skip them magically, it walks them. On top of that, if somebody inserts or deletes between two requests, you will see repeated items or miss some, because the offset is computed over a set that has changed. The alternative is cursor pagination (also called keyset): instead of "skip 100,000", you say "give me the ones after this value".

The cost is constant regardless of depth and it is stable in the face of inserts. The price: you cannot jump to page 37, only move forward. For a catalog with infinite scroll, or an API consumed by machines, it is the right choice.

Point 1 is a classic mistake: { 'sessions.dateTime': { $gte: a, $lt: b } } does not mean "a session inside the range", it means "some session after a and some session before b", which an event with no March session at all can satisfy.

Both options are practically mandatory:

• new: true returns the document after the change. By default — and this surprises everyone — it returns the previous one. Without it you will reply to the client with stale data.
• runValidators: true runs the schema validators. Without it you skip validation entirely: you could set status: 'invented' even though there is an enum, or capacity: -5 even though there is a min: 1. It is Mongoose's biggest and quietest hole. Turn it on globally with mongoose.set('runValidators', true). And watch out for a real limitation: when validating an update, this is the query, not the document, so a validator comparing sold with capacity has no access to capacity unless you are updating that too. The critical invariant cannot rest there alone.

And here comes the first piece of the capacity problem:

Why is this progress? Because $inc does not do read-modify-write in your process: it sends the engine the instruction "add 2 to this field", and the engine applies it under its own document lock. Two simultaneous requests with $inc: 1 leave the counter at +2, never at +1. No more lost updates.

But it is not enough, and it is worth seeing that now so you do not walk away with a false sense of security: $inc adds unconditionally. If one ticket was left and two purchases arrive, both add and sold ends up at capacity + 1. We have solved the lost write, not the checking of the condition. The missing piece — a filter that is part of the same atomic operation — arrives in lesson 07-06.

The reasons are business reasons: accounting (an order that was charged and later cancelled must still show up in the month's close), traceability (with the requestId of Module 6 we can reconstruct what happened, but not if the document no longer exists), referential integrity (with no foreign keys, deleting an order leaves orphan tickets) and human error (a soft delete is reverted by changing a field; a hard one, by restoring a backup, with luck). The price — every query has to filter by status — is low and predictable.

The moment has arrived. src/catalog-data.js exposed getCatalog and getEventById by reading data/events.json. The new module exposes exactly the same, reading MongoDB.

The change in the controllers is literally one line: where src/controllers/events.js used to require('../catalog-data.js'), it now does require('../repositories/events.js'). That is all. listEvents, loadEvent, getEvent and listEventSessions keep working without touching a comma, because they keep receiving domain Event instances with their occupancy, soldOut and revenueCents getters. This is what the repository pattern buys you, and it is the same door Sequelize will walk through in lesson 07-05.

The controller already receives data validated by zod in req.validatedData. What changes is where it comes from and where it goes.

Leave that all-caps comment exactly where it is. It is the course's problem, now with a name and a specific line: we have gained atomicity per operation, but not per set, and on top of that the order and the tickets can be created without the capacity having been reserved, or the other way round. In 07-06 this function will be rewritten from scratch and the comment will disappear.

CastError deserves special attention because it is the most frequent failure in production: a client requests GET /orders/12345 with an identifier that is not an ObjectId, Mongoose cannot cast it and throws. Without translation, your application returns a 500 and your alerting dashboard fills with errors that are not bugs: they are malformed requests and they deserve a 400. The STATUS_BY_CODE table from Module 6 does the rest; you only have to hand it the right code.

• Forgetting runValidators: true. Your enums and your mins stop existing on updates.
• Forgetting new: true. You return the state before the change and spend half an afternoon hunting the bug in the frontend.
• Not using await. An unexecuted Query does not fail: nothing simply happens, or it happens at the wrong time.
• Hydrating full documents only to serialize them. lean() plus a projection is the cheapest optimization there is.
• Paginating with skip on a large catalog. It works until it does not, and it fails exactly when you have traffic.
• Interpolating user input into a $regex. A pattern like (a+)+$ can hang the engine. Always escape.
• Tip: use .orFail() when absence is a real error, and turn on mongoose.set('debug', true) in development: you will see every query that goes out and discover queries you did not know you were making.

Add to src/repositories/orders.js a function listUserOrders(userId, { page, perPage }) returning a user's non-cancelled orders, newest first, projecting sessionId, quantity, totalCents, status and createdAt, using lean(). State which index it needs.

Write searchEvents({ venue, category, from, to, onlyAvailable }) that builds the filter incrementally (adding only the conditions it receives) and returns the published events that match. Use $elemMatch for the date range and $expr for the available tickets.

Implement cancelOrder(orderId) that checks the order exists and is in paid or issued status (otherwise, a StateConflict with INVALID_STATE), marks it as cancelled, marks its tickets as cancelled and returns the capacity. Note down what happens if the process dies between two of those operations.

Exercise 1.

Index: { userId: 1, status: 1, createdAt: -1 }, following the ESR rule — equality first, then the sort field and in the same direction.

Exercise 2.

Exercise 3.

You now know how to move data with Mongoose for real: creating with save() or create() knowing what each one returns, reading with the understanding that a Query is lazy and that lean() plus projections are the most profitable optimization, paginating without falling into the skip trap, filtering with the right operators — including $elemMatch and $expr, which avoid subtle mistakes with arrays — updating without skipping validation and deleting softly so as not to lose the history. And you know how to translate engine errors into the Module 6 hierarchy from the right layer. Above all, src/catalog-data.js is retired: src/repositories/events.js has taken its place with the same signature, the controllers never noticed and the domain still receives its Event instances. The architecture of lesson 07-01 has just proved it was good for something.

One debt remains, written in capitals inside createOrder: $inc has given us atomicity per operation, but not per set, and overselling is still alive. In the next lesson we park that problem a little longer to attack advanced modeling: embedding versus referencing, populate and the N+1 problem, deliberate denormalization, the aggregation framework applied to real Escena Viva reports — which will replace the ones we built in Module 3 by reading CSV files — and indexes taken seriously, with explain() to see whether your queries use them or are scanning the whole collection.