Change Tracking & Context Lifetime

const user = await db.User.where((u) => u.id == $$, id).single(); // tracked (state 'track')
user.blocked = true;                                                   // dirty  (state 'modified')
await db.saveChanges();                                                // one UPDATE, then clean again

const e = db.User.new();          // state: 'insert'   — INSERT on saveChanges()
const u = await db.User.find(1);  // state: 'track'    — loaded, unchanged
u.name = 'Orko';                  // state: 'modified' — UPDATE on saveChanges()
db.User.remove(u);                // state: 'delete'   — DELETE on saveChanges()
db.detach(u);                     // state: 'detached' — no longer part of any save

// EF's context.Entry(entity)
const entry = db.entry(u);
entry.state;                 // 'track' | 'modified' | 'insert' | 'delete' | 'detached' (settable)
entry.originalValues;        // as loaded / last saved
entry.currentValues;
entry.isModified('name');    // pending change on one field (or the whole entity)
await entry.reload();        // database wins: refresh values + originals
await entry.getDatabaseValues(); // live row, entity untouched (null if gone)
entry.detach();

db.hasChanges();             // ChangeTracker.HasChanges()
db.entries('User');          // ChangeTracker.Entries<User>()

// Two units of work on one connection: each save commits ONLY its own dirty set.
const a = await db.User.find(1);
a.plan = 'pro';
await db.saveChanges();      // writes a; leaves every other tracked entity alone

// An empty save is a true no-op — nothing is snapshotted, nothing is untracked.
await db.saveChanges();      // O(1)

// backend/server.js — register the context per request (ASP.NET: services.AddDbContext<AppContext>())
import master from 'mastercontroller';
import AppContext from './app/models/AppContext.js';

master.addScoped('db', AppContext);

// app/controllers/usersController.js — a fresh AppContext per request, disposed when the response closes
export default class UsersController {
  constructor(requestObject) { this.requestObject = requestObject; }

  async block() {
    const user = await this.db.User.find(this.params.id);
    user.blocked = true;
    await this.db.saveChanges();
    this.ok({ id: user.id, blocked: user.blocked });
  }
}

// app/models/db.js — database access OUTSIDE a request (jobs, scripts, hosted services)
import master from 'mastercontroller';

export function withDb(fn) {
  return master.useScope((scope) => fn(scope.db));   // scope disposed (context closed) afterwards
}

// a job
import { withDb } from './app/models/db.js';
await withDb(async (db) => {
  const expired = await db.Session.where((s) => s.expires_at < $$, Date.now()).toList();
  for (const s of expired) db.Session.remove(s);
  await db.saveChanges();
});

// Without MasterController: one context per unit of work, closed at the end
async function handler(req, res) {
  const db = new AppContext();          // cheap: reuses the warm pooled connection
  try {
    const user = await db.User.find(req.params.id);
    user.last_seen = new Date().toISOString();
    await db.saveChanges();
  } finally {
    await db.close();                   // Dispose(): releases the tracker + returns the connection
  }
}

import ContextPool from 'masterrecord/ContextPool';   // or masterrecord.ContextPool

const pool = new ContextPool(AppContext, { maxSize: 64 });

// per request — acquire → run → reset → release, even on error
await pool.use(async (db) => {
  const user = await db.User.asTracking().where((u) => u.id == $$, id).single();
  user.blocked = true;
  await db.saveChanges();
});

await pool.drain();   // at shutdown

// Read-only list: retain nothing (EF AsNoTracking)
const users = await db.User.asNoTracking().toList();

// Context-wide default (EF QueryTrackingBehavior.NoTracking) + opt back in per query
db.setQueryTrackingBehavior('no-track');
const u = await db.User.asTracking().where((x) => x.id == $$, id).single();
u.name = 'Teela';
await db.saveChanges();            // tracked because of asTracking()

// Mutating a no-tracking entity does NOT enqueue a write (it is detached)
const ghost = await db.User.asNoTracking().where((x) => x.id == $$, id).single();
ghost.name = 'nope';
await db.saveChanges();            // nothing written

class Address { constructor() { this.street = null; this.city = null; } }

export default class Customer {
  id(db)      { db.integer().primary().auto(); }
  address(db) { db.owned(Address); }      // JSON column, hydrated into Address on read
  prefs(db)   { db.owned().nullable(); }  // plain object / array
}

const c = await db.Customer.find(1);
c.address.city = 'Paris';          // no column setter fires...
c.prefs.tags.push('vip');
await db.saveChanges();            // ...but DetectChanges compares the serialized value and writes the diff

// Entity loaded elsewhere (another context / service) — EF's context.Update()
const task = await taskService.getTask(taskId);
task.status = 'completed';
db.attach(task);                         // attach + mark modified
await db.saveChanges();

db.attach(task, { status: 'completed' }); // only these fields are written
db.attachAll([task1, task2]);

// Update by primary key without loading first
await db.update('Task', { id: taskId }, { status: 'completed' });
await db.saveChanges();

// Context-level add/remove (EF DbContext.Add / Remove)
db.add(entity);    db.remove(entity);
db.addRange(list); db.removeRange(list);

// Stop tracking
db.detach(entity);        // Entry(e).State = Detached (drops its pending change)
db.clearChangeTracker();  // ChangeTracker.Clear() — drops ALL pending changes
db.reset();               // detach all + clear query cache, connection kept (pool return)
await db.close();         // Dispose(): tracker released, connection returned to the pool warm