How HMR Works

# Entity modification → Server restart → Test
1. Modify Entity in Sonamu UI
2. Ctrl+C (stop server)
3. pnpm dev (restart server)
4. Wait 20-30 seconds...
5. Test

30 seconds wasted each iteration 😫

# Entity modification → Instant reflection
1. Modify Entity in Sonamu UI
2. 🔄 Invalidated log appears in console after 2 seconds
3. Test

2 seconds is enough even with iterations 🚀

// Add nickname to User Entity
nickname: StringProp({ maxLength: 50 });

🔄 Invalidated:
- src/application/user/user.entity.ts
- src/application/user/user.model.ts (with 8 APIs)
- src/application/user/user.api.ts

✅ All files are synced!

# API call without server restart
curl http://localhost:3000/api/user/1
{
  "id": 1,
  "name": "John",
  "nickname": null  // 👈 New field instantly reflected!
}

// user.api.ts before modification
@api({ httpMethod: "GET" })
async list() {
  return UserModel.findMany();
}

// user.api.ts after modification
@api({ httpMethod: "GET" })
async list(listParams: ListParams & { keyword?: string }) {
  const where = listParams.keyword
    ? { name: { $like: `%${listParams.keyword}%` } }
    : undefined;

  return UserModel.findMany({
    where,
    limit: listParams.num,
    offset: (listParams.page - 1) * listParams.num,
  });
}

🔄 Invalidated:
- src/application/user/user.api.ts

✨ API re-registered: GET /api/user/list

GET /api/user/list?keyword=john&page=1&num=10
# Works immediately ✅

// user.model.ts
export class UserModel extends BaseModelClass {
  static async findActive() {
    return this.findMany({
      where: { status: "active", deletedAt: null },
    });
  }

  isActive(): boolean {
    return this.status === "active" && !this.deletedAt;
  }
}

// post.api.ts
@api({ httpMethod: "POST" })
async create(body: PostForm) {
  const user = await UserModel.findById(body.userId);

  if (!user.isActive()) {  // 👈 Use the method just added!
    throw new BadRequestException("User is not active");
  }

  return PostModel.save(body);
}

User Entity modified
  ↓
Syncer starts generating files...
  ↓
HMR detects and starts reloading... ← 🚨 Still generating!
  ↓
Timing mismatch → Errors occur

// syncer.ts
async hmrAndSync(fileEvents: Map<AbsolutePath, "change" | "add">) {
  // 1. HMR concern: invalidate the api/src module graph
  //    (independent of the cpg — checksum pattern group — match)
  for (const [filePath, event] of fileEvents) {
    await hot.invalidateFile(filePath, event);
  }

  // 2. Sync concern: run doSyncActions for files matching the cpg
  //    (auto-generated code sync completes — order guaranteed!)
  await this.doSyncActions(matchedFiles);

  // 3. Now safely reload modules
  await this.autoloadTypes();
  await this.autoloadModels();
  await this.autoloadApis();
  await this.autoloadWorkflows();

  // 4. Done!
  this.eventEmitter.emit("onHMRCompleted");
}

// hmr-hook-register.ts
if (process.env.HOT === "yes" && process.env.API_ROOT_PATH) {
  const { hot } = await import("@sonamu-kit/hmr-hook");

  await hot.init({
    rootDirectory: process.env.API_ROOT_PATH,
    boundaries: [`./src/**/*.ts`], // All .ts files are HMR targets
  });

  console.log("🔥 HMR-hook initialized");
}

user.model.ts
  ├─ user.api.ts
  ├─ post.api.ts
  └─ admin.api.ts

// First-pass guard: drop irrelevant events at the watcher entry
//   - isWantedEvent: only "change" | "add" pass through (no unlink)
//   - isConfigChange: sonamu.config.ts is routed separately
//   - isOutOfScope: cut unless it lives in api/src or matches the cpg
//   - isLastChangedByMe: filter out self-write echoes (mtime check)
const fileEvents = await collectBatch(); // 100ms global trailing debounce

await syncer.hmrAndSync(fileEvents);

// Monitor filesystem with chokidar
watcher.on("change", (filePath) => {
  console.log(`File changed: ${filePath}`);
});

// Remove ESM cache
const invalidatedPaths = await hot.invalidateFile(diffFilePath, "change");
// ["src/user/user.model.ts", "src/user/user.api.ts", ...]

await this.doSyncActions([diffFilePath]);

await this.autoloadTypes();
await this.autoloadModels();
await this.autoloadApis();
await this.autoloadWorkflows();

removeInvalidatedRegisteredApis(invalidatedPath: AbsolutePath) {
  const entityId = EntityManager.getEntityIdFromPath(invalidatedPath);
  const toRemove = registeredApis.filter((api) => api.modelName === `${entityId}Model`);

  for (const api of toRemove) {
    registeredApis.splice(registeredApis.indexOf(api), 1);
  }

  return toRemove;
}

🔄 Invalidated:
- src/user/user.model.ts (with 8 APIs)

// Original hot-hook: ❌ Not possible
const modelPath = `./models/${entityId}.model`;
await import(modelPath); // Error!

// Sonamu hmr-hook: ✅ Possible
const modelPath = `./models/${entityId}.model`;
await import(modelPath); // Works

// user.model.ts (boundary)
import { PostModel } from "./post.model"; // Original: ❌ / Sonamu: ✅

export class UserModel extends BaseModelClass {
  async getPosts() {
    return PostModel.findMany({ where: { userId: this.id } });
  }
}

// When Syncer detects file change, notify HMR directly
await hot.invalidateFile(filePath, "change");

// user.types.ts change → only user.model.ts reloads
// Not the entire project, just affected files!

const changedFiles = await findChangedFilesUsingChecksums();
if (changedFiles.length === 0) {
  console.log(chalk.black.bgGreen("All files are synced!"));
  return;
}

await runWithGracefulShutdown(
  async () => {
    await this.doSyncActions(changedFiles);
    await renewChecksums();
  },
  { whenThisHappens: "SIGUSR2", waitForUpTo: 20000 },
);

pnpm dev  # HOT=yes is auto-set

# Enable HMR
HOT=yes pnpm dev

# Disable HMR (for debugging)
HOT=no pnpm dev

// Check logs printed in terminal
🔥 HMR-hook initialized

// On file change
🔄 Invalidated:
- src/user/user.model.ts (with 8 APIs)
- src/user/user.api.ts

✅ All files are synced!

# Check dependency tree
const dump = await hot.dump();
console.log(`Total modules: ${dump.length}`);
console.log(`Boundaries: ${dump.filter(d => d.boundary).length}`);