@nexa-stack/framework 1.0.0

package/packages/core/src/reload.ts

@@ -0,0 +1,92 @@
+import { join } from "path";
+import { existsSync, watch } from "fs";
+import { clearRegistry, getResources, registerResource } from "./registry.js";
+import { loadResources, importFreshTs } from "./loader.js";
+import { clearLangCache } from "./lang.js";
+import { clearCustomRoutes, getCustomRoutes } from "./routes.js";
+import { recordDevReload } from "./dev.js";
+import { syncResourceTables } from "./migrate.js";
+import type { Router } from "../../server/src/router.js";
+import type { Database } from "../../database/src/database.js";
+import { log } from "../../log/src/index.js";
+import { config } from "./config.js";
+
+let reloadTimer: ReturnType<typeof setTimeout> | null = null;
+
+function restoreRegistry(snapshot: ReturnType<typeof getResources>, router: Router): void {
+  clearRegistry();
+  for (const def of snapshot) registerResource(def);
+  router.reloadResources();
+}
+
+/** Re-import app + resources and refresh API routes (dev hot reload). */
+export async function reloadApplication(
+  router: Router,
+  db: Database,
+  cwd = process.cwd()
+): Promise<number> {
+  const snapshot = getResources().map((d) => ({ ...d, fields: { ...d.fields } }));
+
+  clearRegistry();
+  clearLangCache();
+  clearCustomRoutes();
+
+  try {
+    const appFile = join(cwd, "app.ts");
+    if (existsSync(appFile)) await importFreshTs(appFile);
+
+    const count = await loadResources(cwd, { reload: true });
+    const loaded = getResources();
+
+    if (loaded.length === 0 && snapshot.length > 0) {
+      restoreRegistry(snapshot, router);
+      throw new Error("Reload produced 0 resources — kept previous registry");
+    }
+
+    await syncResourceTables(db);
+    router.reloadResources();
+    router.registerCustomRoutes([...getCustomRoutes()]);
+    recordDevReload(getResources().length);
+    return count;
+  } catch (err) {
+    if (getResources().length === 0 && snapshot.length > 0) {
+      restoreRegistry(snapshot, router);
+    }
+    recordDevReload(snapshot.length, String(err));
+    throw err;
+  }
+}
+
+function scheduleReload(router: Router, db: Database, cwd: string): void {
+  if (reloadTimer) clearTimeout(reloadTimer);
+  reloadTimer = setTimeout(async () => {
+    try {
+      const n = await reloadApplication(router, db, cwd);
+      log.info(`Hot reload — ${getResources().length} resource(s)${n ? `, ${n} file(s) in resources/` : ""}`);
+    } catch (err) {
+      log.error("Hot reload failed", { err: String(err) });
+    }
+  }, 280);
+}
+
+/** Watch app.ts and resources/*.ts — enabled by default outside production. */
+export function startHotReload(router: Router, db: Database, cwd = process.cwd()): void {
+  if (config("HOT_RELOAD") === "false") return;
+  if (config("NODE_ENV") === "production") return;
+
+  const appFile = join(cwd, "app.ts");
+  if (existsSync(appFile)) {
+    watch(appFile, () => scheduleReload(router, db, cwd));
+  }
+
+  const resourcesDir = join(cwd, "resources");
+  if (existsSync(resourcesDir)) {
+    watch(resourcesDir, { recursive: true }, (_event, file) => {
+      if (file && !file.endsWith(".ts")) return;
+      if (file?.includes(".nexa-reload-")) return;
+      scheduleReload(router, db, cwd);
+    });
+  }
+
+  log.info("Hot reload on — edit app.ts or resources/ without restart");
+}

package/packages/core/src/resource.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "vitest";
+import { resource } from "./resource.js";
+import { string, number } from "./fields.js";
+import { getResources } from "./registry.js";
+
+describe("resource", () => {
+  test("auto registers with crud and api", () => {
+    const before = getResources().length;
+    resource("items", { name: string().required(), qty: number() }, { label: "عناصر" })
+      .auth("admin")
+      .admin();
+    const def = getResources()[getResources().length - 1];
+    expect(getResources().length).toBe(before + 1);
+    expect(def.label).toBe("عناصر");
+    expect(def.hasAdmin).toBe(true);
+    expect(def.authRole).toBe("admin");
+    expect(def.softDelete).toBe(true);
+  });
+
+  test("hardDeletes() disables soft delete on admin resources", () => {
+    resource("hard_demo", { name: string().required() }).admin().hardDeletes();
+    const def = getResources()[getResources().length - 1];
+    expect(def.softDelete).toBe(false);
+  });
+
+  test("admin() implies auth when missing", () => {
+    resource("locked_demo", { name: string().required() }).admin();
+    const def = getResources()[getResources().length - 1];
+    expect(def.hasAdmin).toBe(true);
+    expect(def.authRole).toBe("admin");
+  });
+});

package/packages/core/src/resource.ts

@@ -0,0 +1,87 @@
+import { resolveFields, type FieldBuilder, type FieldDef } from "./fields.js";
+import { registerResource } from "./registry.js";
+import type { ResourcePolicy } from "./policy.js";
+import { policyFromRole } from "./policy.js";
+
+type Fields = Record<string, FieldBuilder>;
+
+export interface ResourceOptions {
+  label?: string;
+  labelKey?: string;
+}
+
+export interface ResourceDefinition {
+  name: string;
+  label: string;
+  labelKey: string | null;
+  table: string;
+  fields: Record<string, FieldDef>;
+  hasCrud: boolean;
+  hasApi: boolean;
+  authRole: string | null;
+  policy: ResourcePolicy | null;
+  hasAdmin: boolean;
+  softDelete: boolean;
+}
+
+export class Resource {
+  private def: ResourceDefinition;
+
+  constructor(name: string, fields: Fields, opts: ResourceOptions = {}) {
+    this.def = {
+      name,
+      label: opts.label ?? opts.labelKey ?? name,
+      labelKey: opts.labelKey ?? null,
+      table: name.toLowerCase(),
+      fields: resolveFields(fields),
+      hasCrud: true,
+      hasApi: true,
+      authRole: null,
+      policy: null,
+      hasAdmin: false,
+      softDelete: false,
+    };
+    registerResource(this.def);
+  }
+
+  auth(role = "admin"): this {
+    this.def.authRole = role;
+    this.def.policy = policyFromRole(role);
+    return this;
+  }
+
+  policy(rules: ResourcePolicy | string): this {
+    this.def.policy = typeof rules === "string" ? policyFromRole(rules) : rules;
+    return this;
+  }
+
+  admin(): this {
+    this.def.hasAdmin = true;
+    this.def.softDelete = true;
+    // Admin UI resources must not be world-writable by default
+    if (!this.def.authRole) {
+      this.def.authRole = "admin";
+      this.def.policy = policyFromRole("admin");
+    }
+    return this;
+  }
+
+  /** Disable soft delete (admin() enables it by default). */
+  hardDeletes(): this {
+    this.def.softDelete = false;
+    return this;
+  }
+
+  softDeletes(): this {
+    this.def.softDelete = true;
+    return this;
+  }
+
+  getDefinition(): ResourceDefinition {
+    return this.def;
+  }
+}
+
+export function resource(name: string, fields: Fields, opts?: ResourceOptions): Resource {
+  return new Resource(name, fields, opts);
+}

package/packages/core/src/routes.ts

@@ -0,0 +1,22 @@
+import type { AuthUser } from "../../auth/src/auth.js";
+
+export type RouteHandler = (
+  req: Request,
+  user: AuthUser | null
+) => Promise<Response> | Response;
+
+const customRoutes: { method: string; path: string; handler: RouteHandler }[] = [];
+
+/** Register a custom API route — mounted when `start()` runs. */
+export function route(method: string, path: string, handler: RouteHandler): void {
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  customRoutes.push({ method: method.toUpperCase(), path: normalized, handler });
+}
+
+export function getCustomRoutes(): readonly { method: string; path: string; handler: RouteHandler }[] {
+  return customRoutes;
+}
+
+export function clearCustomRoutes(): void {
+  customRoutes.length = 0;
+}

package/packages/core/src/runtime.ts

@@ -0,0 +1,11 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Directory of the calling ESM module (`import.meta.url`). */
+export function moduleDir(importMetaUrl: string): string {
+  return dirname(fileURLToPath(importMetaUrl));
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/packages/database/src/builder.ts

@@ -0,0 +1,266 @@
+import type { Database } from "./database.js";
+import type { DbRow } from "./types.js";
+import { safeIdent } from "./query.js";
+import { getResources } from "../../core/src/registry.js";
+import { fieldColumn, foreignKeyFor, pivotTableFor } from "../../core/src/fields.js";
+
+type BoolOp = "and" | "or";
+
+interface WhereClause {
+  sql: string;
+  params: unknown[];
+  op: BoolOp;
+}
+
+/** Fluent query builder */
+export class QueryBuilder {
+  private wheres: WhereClause[] = [];
+  private orderSql: string | null = null;
+  private limitN: number | null = null;
+  private offsetN: number | null = null;
+  private withRels: string[] = [];
+
+  constructor(
+    private db: Database,
+    private table: string
+  ) {
+    this.table = safeIdent(table, "");
+    if (!this.table) throw new Error("Invalid table name");
+  }
+
+  where(column: string, operatorOrValue: unknown, value?: unknown): this {
+    return this.addWhere("and", column, operatorOrValue, value);
+  }
+
+  orWhere(column: string, operatorOrValue: unknown, value?: unknown): this {
+    return this.addWhere("or", column, operatorOrValue, value);
+  }
+
+  whereIn(column: string, values: unknown[]): this {
+    const col = safeIdent(column, "");
+    if (!col || values.length === 0) {
+      this.wheres.push({ sql: "1=0", params: [], op: "and" });
+      return this;
+    }
+    const ph = values.map(() => "?").join(", ");
+    this.wheres.push({ sql: `${col} IN (${ph})`, params: values, op: "and" });
+    return this;
+  }
+
+  whereNull(column: string): this {
+    const col = safeIdent(column, "");
+    if (!col) return this;
+    this.wheres.push({ sql: `${col} IS NULL`, params: [], op: "and" });
+    return this;
+  }
+
+  whereNotNull(column: string): this {
+    const col = safeIdent(column, "");
+    if (!col) return this;
+    this.wheres.push({ sql: `${col} IS NOT NULL`, params: [], op: "and" });
+    return this;
+  }
+
+  orderBy(column: string, direction: "asc" | "desc" = "asc"): this {
+    const col = safeIdent(column, "id");
+    this.orderSql = `${col} ${direction === "asc" ? "ASC" : "DESC"}`;
+    return this;
+  }
+
+  limit(n: number): this {
+    this.limitN = Math.max(0, n);
+    return this;
+  }
+
+  offset(n: number): this {
+    this.offsetN = Math.max(0, n);
+    return this;
+  }
+
+  with(...relations: string[]): this {
+    this.withRels.push(...relations);
+    return this;
+  }
+
+  async get(): Promise<DbRow[]> {
+    const { sql, params } = this.buildSelect();
+    const rows = await this.db.query(sql, params);
+    return this.eager(rows);
+  }
+
+  async first(): Promise<DbRow | null> {
+    const prev = this.limitN;
+    this.limitN = 1;
+    const rows = await this.get();
+    this.limitN = prev;
+    return rows[0] ?? null;
+  }
+
+  async count(): Promise<number> {
+    const { where, params } = this.buildWhere();
+    const sql = `SELECT COUNT(*) as total FROM ${this.table} ${where}`;
+    const row = await this.db.getOne(sql, params);
+    return Number(row?.total ?? 0);
+  }
+
+  async sum(column: string): Promise<number> {
+    const col = safeIdent(column, "");
+    if (!col) return 0;
+    const { where, params } = this.buildWhere();
+    const sql = `SELECT COALESCE(SUM(${col}), 0) as total FROM ${this.table} ${where}`;
+    const row = await this.db.getOne(sql, params);
+    return Number(row?.total ?? 0);
+  }
+
+  async insert(data: Record<string, unknown>): Promise<DbRow> {
+    return this.db.insert(this.table, data);
+  }
+
+  async update(data: Record<string, unknown>): Promise<number> {
+    const keys = Object.keys(data);
+    if (keys.length === 0) return 0;
+    const { where, params } = this.buildWhere();
+    if (!where) throw new Error("Refusing update without where()");
+    const set = keys.map((k) => `${safeIdent(k, k)} = ?`).join(", ");
+    await this.db.run(`UPDATE ${this.table} SET ${set} ${where}`, [
+      ...keys.map((k) => data[k]),
+      ...params,
+    ]);
+    return this.count();
+  }
+
+  async delete(): Promise<number> {
+    const { where, params } = this.buildWhere();
+    if (!where) throw new Error("Refusing delete without where()");
+    const before = await this.count();
+    await this.db.run(`DELETE FROM ${this.table} ${where}`, params);
+    return before;
+  }
+
+  private addWhere(
+    op: BoolOp,
+    column: string,
+    operatorOrValue: unknown,
+    value?: unknown
+  ): this {
+    const col = safeIdent(column, "");
+    if (!col) return this;
+    let operator = "=";
+    let val = operatorOrValue;
+    if (value !== undefined) {
+      operator = String(operatorOrValue);
+      val = value;
+    }
+    const allowed = ["=", "!=", "<>", "<", ">", "<=", ">=", "like", "LIKE"];
+    if (!allowed.includes(operator)) operator = "=";
+    this.wheres.push({ sql: `${col} ${operator} ?`, params: [val], op });
+    return this;
+  }
+
+  private buildWhere(): { where: string; params: unknown[] } {
+    if (this.wheres.length === 0) return { where: "", params: [] };
+    const params: unknown[] = [];
+    let sql = "";
+    for (let i = 0; i < this.wheres.length; i++) {
+      const w = this.wheres[i];
+      if (i === 0) sql = w.sql;
+      else sql += ` ${w.op.toUpperCase()} ${w.sql}`;
+      params.push(...w.params);
+    }
+    return { where: `WHERE ${sql}`, params };
+  }
+
+  private buildSelect(): { sql: string; params: unknown[] } {
+    const { where, params } = this.buildWhere();
+    let sql = `SELECT * FROM ${this.table} ${where}`;
+    if (this.orderSql) sql += ` ORDER BY ${this.orderSql}`;
+    else sql += ` ORDER BY id DESC`;
+    if (this.limitN != null) {
+      sql += ` LIMIT ?`;
+      params.push(this.limitN);
+    }
+    if (this.offsetN != null) {
+      sql += ` OFFSET ?`;
+      params.push(this.offsetN);
+    }
+    return { sql, params };
+  }
+
+  private async eager(rows: DbRow[]): Promise<DbRow[]> {
+    if (rows.length === 0 || this.withRels.length === 0) return rows;
+    const resource = getResources().find((r) => r.table === this.table || r.name === this.table);
+    if (!resource) return rows;
+
+    const out = rows.map((r) => ({ ...r }));
+    for (const relName of this.withRels) {
+      const field = resource.fields[relName];
+      if (!field?.relation) continue;
+
+      if (field.type === "relation" && field.relationMode === "belongsTo") {
+        const col = fieldColumn(relName, field)!;
+        const ids = [...new Set(out.map((r) => Number(r[col])).filter((id) => id > 0))];
+        if (ids.length === 0) continue;
+        const related = await this.db.query(
+          `SELECT * FROM ${safeIdent(field.relation)} WHERE id IN (${ids.map(() => "?").join(",")})`,
+          ids
+        );
+        const map = new Map(related.map((r) => [Number(r.id), r]));
+        for (const row of out) {
+          row[relName] = map.get(Number(row[col])) ?? null;
+        }
+        continue;
+      }
+
+      if (field.type === "hasMany" && field.relation) {
+        const fk = foreignKeyFor(resource.table);
+        const ids = out.map((r) => Number(r.id));
+        const related = await this.db.query(
+          `SELECT * FROM ${safeIdent(field.relation)} WHERE ${fk} IN (${ids.map(() => "?").join(",")})`,
+          ids
+        );
+        const grouped = new Map<number, DbRow[]>();
+        for (const r of related) {
+          const key = Number(r[fk]);
+          if (!grouped.has(key)) grouped.set(key, []);
+          grouped.get(key)!.push(r);
+        }
+        for (const row of out) {
+          row[relName] = grouped.get(Number(row.id)) ?? [];
+        }
+        continue;
+      }
+
+      if (field.type === "belongsToMany" && field.relation) {
+        const pivot = field.pivot ?? pivotTableFor(resource.table, field.relation);
+        const localKey = foreignKeyFor(resource.table);
+        const foreignKey = foreignKeyFor(field.relation);
+        const ids = out.map((r) => Number(r.id));
+        const pivots = await this.db.query(
+          `SELECT * FROM ${safeIdent(pivot)} WHERE ${localKey} IN (${ids.map(() => "?").join(",")})`,
+          ids
+        );
+        const foreignIds = [...new Set(pivots.map((p) => Number(p[foreignKey])))];
+        const related =
+          foreignIds.length === 0
+            ? []
+            : await this.db.query(
+                `SELECT * FROM ${safeIdent(field.relation)} WHERE id IN (${foreignIds.map(() => "?").join(",")})`,
+                foreignIds
+              );
+        const relMap = new Map(related.map((r) => [Number(r.id), r]));
+        const byLocal = new Map<number, DbRow[]>();
+        for (const p of pivots) {
+          const lid = Number(p[localKey]);
+          const rel = relMap.get(Number(p[foreignKey]));
+          if (!rel) continue;
+          if (!byLocal.has(lid)) byLocal.set(lid, []);
+          byLocal.get(lid)!.push(rel);
+        }
+        for (const row of out) {
+          row[relName] = byLocal.get(Number(row.id)) ?? [];
+        }
+      }
+    }
+    return out;
+  }
+}