@nexa-stack/framework 1.0.0

package/packages/cache/src/index.ts

@@ -0,0 +1,203 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, readdirSync } from "fs";
+import { join } from "path";
+
+interface CacheEntry {
+  value: unknown;
+  expires: number | null;
+}
+
+const memory = new Map<string, CacheEntry>();
+let redis: any = null;
+
+function driver(): "memory" | "file" | "redis" {
+  const d = process.env.CACHE_DRIVER || "memory";
+  if (d === "file" || d === "redis") return d;
+  return "memory";
+}
+
+function fileDir(): string {
+  const dir = join(process.cwd(), "storage", "cache");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function filePath(key: string): string {
+  const safe = key.replace(/[^a-zA-Z0-9._-]/g, "_");
+  return join(fileDir(), `${safe}.json`);
+}
+
+function isAlive(entry: CacheEntry | null | undefined): entry is CacheEntry {
+  if (!entry) return false;
+  if (entry.expires !== null && Date.now() > entry.expires) return false;
+  return true;
+}
+
+async function getRedis(): Promise<any> {
+  if (redis) return redis;
+  const url = process.env.REDIS_URL || "redis://127.0.0.1:6379";
+  try {
+    const { default: Redis } = await import("ioredis");
+    redis = new Redis(url);
+    return redis;
+  } catch {
+    throw new Error(
+      "CACHE_DRIVER=redis requires Redis. Set REDIS_URL and install optional peer ioredis."
+    );
+  }
+}
+
+export const cache = {
+  async get<T = unknown>(key: string): Promise<T | null> {
+    const d = driver();
+    if (d === "redis") {
+      const r = await getRedis();
+      const raw = await r.get(`nexa:${key}`);
+      if (raw == null) return null;
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        return raw as T;
+      }
+    }
+    if (d === "file") {
+      try {
+        if (!existsSync(filePath(key))) return null;
+        const entry = JSON.parse(readFileSync(filePath(key), "utf-8")) as CacheEntry;
+        if (!isAlive(entry)) {
+          unlinkSync(filePath(key));
+          return null;
+        }
+        return entry.value as T;
+      } catch {
+        return null;
+      }
+    }
+    const entry = memory.get(key);
+    if (!isAlive(entry)) {
+      memory.delete(key);
+      return null;
+    }
+    return entry.value as T;
+  },
+
+  async set(key: string, value: unknown, seconds?: number): Promise<void> {
+    const d = driver();
+    if (d === "redis") {
+      const r = await getRedis();
+      const raw = JSON.stringify(value);
+      if (seconds) await r.set(`nexa:${key}`, raw, "EX", seconds);
+      else await r.set(`nexa:${key}`, raw);
+      return;
+    }
+    const entry: CacheEntry = {
+      value,
+      expires: seconds ? Date.now() + seconds * 1000 : null,
+    };
+    if (d === "file") {
+      writeFileSync(filePath(key), JSON.stringify(entry));
+      return;
+    }
+    memory.set(key, entry);
+  },
+
+  async forget(key: string): Promise<void> {
+    const d = driver();
+    if (d === "redis") {
+      const r = await getRedis();
+      await r.del(`nexa:${key}`);
+      return;
+    }
+    if (d === "file") {
+      try {
+        if (existsSync(filePath(key))) unlinkSync(filePath(key));
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    memory.delete(key);
+  },
+
+  async flush(): Promise<void> {
+    const d = driver();
+    if (d === "redis") {
+      const r = await getRedis();
+      const keys = await r.keys("nexa:*");
+      if (keys.length) await r.del(...keys);
+      return;
+    }
+    if (d === "file") {
+      for (const f of readdirSync(fileDir())) {
+        try {
+          unlinkSync(join(fileDir(), f));
+        } catch {
+          /* ignore */
+        }
+      }
+      return;
+    }
+    memory.clear();
+  },
+
+  async remember<T>(key: string, seconds: number, fn: () => T | Promise<T>): Promise<T> {
+    const hit = await this.get<T>(key);
+    if (hit !== null) return hit;
+    const value = await fn();
+    await this.set(key, value, seconds);
+    return value;
+  },
+
+  /** Atomic increment — used by distributed rate limiting */
+  async incr(key: string, windowSeconds?: number): Promise<number> {
+    const d = driver();
+    if (d === "redis") {
+      const r = await getRedis();
+      const full = `nexa:${key}`;
+      const n = Number(await r.incr(full));
+      if (n === 1 && windowSeconds) {
+        try {
+          await r.expire(full, windowSeconds);
+        } catch {
+          /* ioredis API differences */
+          try {
+            await r.set(full, String(n), "EX", windowSeconds, "XX");
+          } catch {
+            /* ignore */
+          }
+        }
+      }
+      return n;
+    }
+    const current = (await this.get<number>(key)) ?? 0;
+    const next = current + 1;
+    await this.set(key, next, windowSeconds);
+    return next;
+  },
+
+  /** Delete keys with a prefix (list cache invalidation) */
+  async forgetPrefix(prefix: string): Promise<void> {
+    const d = driver();
+    if (d === "redis") {
+      const r = await getRedis();
+      const keys = await r.keys(`nexa:${prefix}*`);
+      if (keys?.length) await r.del(...keys);
+      return;
+    }
+    if (d === "file") {
+      const safePrefix = prefix.replace(/[^a-zA-Z0-9._-]/g, "_");
+      for (const f of readdirSync(fileDir())) {
+        if (f.startsWith(safePrefix)) {
+          try {
+            unlinkSync(join(fileDir(), f));
+          } catch {
+            /* ignore */
+          }
+        }
+      }
+      return;
+    }
+    for (const key of [...memory.keys()]) {
+      if (key.startsWith(prefix)) memory.delete(key);
+    }
+  },
+};

package/packages/client/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Thin fetch client for a future Nexa frontend — no UI, just API helpers.
+ */
+export interface NexaClientOptions {
+  baseUrl?: string;
+  token?: string | (() => string | null | undefined);
+}
+
+export function createClient(opts: NexaClientOptions = {}) {
+  const base = (opts.baseUrl ?? "").replace(/\/+$/, "");
+
+  async function request(method: string, path: string, body?: unknown) {
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    const token = typeof opts.token === "function" ? opts.token() : opts.token;
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(`${base}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      const err = new Error((json as { error?: string }).error || res.statusText);
+      (err as Error & { status: number; body: unknown }).status = res.status;
+      (err as Error & { status: number; body: unknown }).body = json;
+      throw err;
+    }
+    return json;
+  }
+
+  return {
+    get: (path: string) => request("GET", path),
+    post: (path: string, body?: unknown) => request("POST", path, body),
+    put: (path: string, body?: unknown) => request("PUT", path, body),
+    del: (path: string) => request("DELETE", path),
+    resource(name: string) {
+      const basePath = `/api/${name}`;
+      return {
+        list: (qs = "") => request("GET", `${basePath}${qs}`),
+        get: (id: number | string) => request("GET", `${basePath}/${id}`),
+        create: (body: unknown) => request("POST", basePath, body),
+        update: (id: number | string, body: unknown) => request("PUT", `${basePath}/${id}`, body),
+        remove: (id: number | string) => request("DELETE", `${basePath}/${id}`),
+      };
+    },
+    login: (email: string, password: string) =>
+      request("POST", "/api/auth/login", { email, password }),
+  };
+}

package/packages/core/src/app.ts

@@ -0,0 +1,97 @@
+import { join } from "path";
+import { loadEnv, config, configNumber, assertProductionReady, isAuthRegisterEnabled } from "./config.js";
+import { getResources } from "./registry.js";
+import { loadResources } from "./loader.js";
+import { moduleDir } from "./runtime.js";
+import { dbConnection, type Database } from "../../database/src/database.js";
+import { Router, createServer } from "../../server/src/router.js";
+import { use, rateLimit, cors, clearMiddleware } from "../../server/src/middleware.js";
+import { setupAuth, seedAdmin } from "../../auth/src/index.js";
+import { runMigrations, runSeeders } from "./migrate.js";
+import { setupQueue, registerBuiltInJobs } from "../../queue/src/index.js";
+import { setupNotifications } from "../../notifications/src/index.js";
+import { bootPlugins } from "../../plugins/src/index.js";
+import { log } from "../../log/src/index.js";
+
+loadEnv();
+
+let dbInstance: Database | null = null;
+
+/** Framework package `public/` — used when the app has no local copy */
+function packagePublicDir(): string {
+  return join(moduleDir(import.meta.url), "../../../public");
+}
+
+export async function start(dbPath?: string, port?: number) {
+  assertProductionReady();
+  const path = dbPath ?? dbConnection();
+  const serverPort = port ?? configNumber("PORT");
+
+  await loadResources();
+
+  dbInstance = await runMigrations(path);
+  await setupQueue(dbInstance);
+  registerBuiltInJobs();
+  await setupNotifications(dbInstance);
+  await bootPlugins();
+
+  await setupAuth({ secret: config("APP_SECRET") }, dbInstance);
+  if (config("APP_SECRET") === "change-me") {
+    log.warn("APP_SECRET is the default — set a strong secret before any public deploy");
+  }
+  await seedAdmin(dbInstance);
+  await runSeeders(dbInstance);
+
+  clearMiddleware();
+  use(cors());
+  const limit = Number(config("RATE_LIMIT") || 120);
+  if (limit > 0) use(rateLimit(limit, 60_000));
+
+  const router = new Router(dbInstance, join(process.cwd(), "public"), packagePublicDir());
+  for (const def of getResources()) router.registerResource(def);
+  router.registerAuthRoutes();
+  router.registerNotificationRoutes();
+  const { getCustomRoutes } = await import("./routes.js");
+  router.registerCustomRoutes([...getCustomRoutes()]);
+
+  const { startHotReload } = await import("./reload.js");
+  startHotReload(router, dbInstance);
+
+  const server = await createServer(router, serverPort);
+  const { setDevPort } = await import("./dev.js");
+  setDevPort(server.port);
+  log.info(`Nexa → http://localhost:${server.port} (${dbInstance.dialect})`);
+  if (config("NODE_ENV") !== "production") {
+    log.info("Dev bar → open /admin or /docs (bottom toolbar)");
+  }
+  return server;
+}
+
+export function getDb(): Database | null {
+  return dbInstance;
+}
+
+/** Open / migrate DB (tests + CLI). Also exposes db.from / db.transaction */
+async function openDb(path?: string): Promise<Database> {
+  dbInstance = await runMigrations(path ?? dbConnection());
+  return dbInstance;
+}
+
+export const db = Object.assign(openDb, {
+  from(table: string) {
+    const instance = getDb();
+    if (!instance) throw new Error("Call start() or await db() first");
+    return instance.from(table);
+  },
+  table(table: string) {
+    return db.from(table);
+  },
+  transaction<T>(fn: (tx: Database) => Promise<T>): Promise<T> {
+    const instance = getDb();
+    if (!instance) throw new Error("Call start() or await db() first");
+    return instance.transaction(fn);
+  },
+});
+
+export const connect = start;
+export const serve = start;

package/packages/core/src/config.ts

@@ -0,0 +1,55 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const defaults: Record<string, string> = {
+  DB_PATH: "./app.db",
+  PORT: "3333",
+  APP_SECRET: "change-me",
+  APP_LOCALE: "en",
+  APP_URL: "http://localhost:3333",
+  MAIL_DRIVER: "log",
+  MAIL_FROM: "nexa@localhost",
+  LOG_LEVEL: "debug",
+  CACHE_DRIVER: "memory",
+  AUTH_RATE_LIMIT: "10",
+};
+
+export function loadEnv(root = process.cwd()): void {
+  const envPath = join(root, ".env");
+  if (!existsSync(envPath)) return;
+  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const i = trimmed.indexOf("=");
+    if (i === -1) continue;
+    const key = trimmed.slice(0, i).trim();
+    const val = trimmed.slice(i + 1).trim();
+    if (!process.env[key]) process.env[key] = val;
+  }
+}
+
+export function config(key: string): string {
+  return process.env[key] ?? defaults[key] ?? "";
+}
+
+export function configNumber(key: string): number {
+  return Number(config(key));
+}
+
+/** Public sign-up: enabled in dev; disabled in production unless AUTH_REGISTER=true. */
+export function isAuthRegisterEnabled(): boolean {
+  const raw = process.env.AUTH_REGISTER;
+  if (raw?.toLowerCase() === "true") return true;
+  if (raw?.toLowerCase() === "false") return false;
+  return config("NODE_ENV") !== "production";
+}
+
+export function assertProductionReady(): void {
+  if (config("NODE_ENV") !== "production") return;
+  const secret = config("APP_SECRET");
+  if (!secret || secret === "change-me" || secret.length < 32) {
+    throw new Error(
+      "Production requires APP_SECRET — set a random string of at least 32 characters in .env"
+    );
+  }
+}

package/packages/core/src/dev.ts

@@ -0,0 +1,104 @@
+import { config } from "./config.js";
+import { getResources } from "./registry.js";
+
+export interface DevRequestLog {
+  method: string;
+  path: string;
+  status: number;
+  ms: number;
+  at: string;
+}
+
+export interface DevRouteEntry {
+  method: string;
+  path: string;
+  group: string;
+}
+
+const MAX_REQUESTS = 30;
+
+let startedAt = new Date().toISOString();
+let port = 3333;
+let lastReloadAt: string | null = null;
+let lastReloadError: string | null = null;
+let lastReloadResources = 0;
+const recentRequests: DevRequestLog[] = [];
+
+export function isDevMode(): boolean {
+  return config("NODE_ENV") !== "production";
+}
+
+export function isHotReloadEnabled(): boolean {
+  return isDevMode() && config("HOT_RELOAD") !== "false";
+}
+
+export function resetDevState(): void {
+  startedAt = new Date().toISOString();
+  lastReloadAt = null;
+  lastReloadError = null;
+  lastReloadResources = 0;
+  recentRequests.length = 0;
+}
+
+export function setDevPort(value: number): void {
+  port = value;
+}
+
+export function recordDevReload(resourceCount: number, err?: string): void {
+  lastReloadAt = new Date().toISOString();
+  lastReloadResources = resourceCount;
+  lastReloadError = err ?? null;
+}
+
+export function recordDevRequest(
+  method: string,
+  path: string,
+  status: number,
+  ms: number
+): void {
+  if (!isDevMode()) return;
+  if (path === "/dev-bar.js" || path.startsWith("/api/dev/")) return;
+
+  recentRequests.unshift({
+    method,
+    path,
+    status,
+    ms: Math.round(ms),
+    at: new Date().toISOString(),
+  });
+  if (recentRequests.length > MAX_REQUESTS) recentRequests.pop();
+}
+
+export function getDevStatus(routeCount = 0) {
+  return {
+    dev: true,
+    port,
+    started_at: startedAt,
+    hot_reload: isHotReloadEnabled(),
+    node_env: config("NODE_ENV") || "development",
+    dialect: null as string | null,
+    resources: getResources().length,
+    routes: routeCount,
+    last_reload_at: lastReloadAt,
+    last_reload_error: lastReloadError,
+    last_reload_resources: lastReloadResources,
+    recent_requests: [...recentRequests],
+  };
+}
+
+export function groupRouteKey(key: string, resourceKeys: Set<string>, customKeys: Set<string>): DevRouteEntry {
+  const space = key.indexOf(" ");
+  const method = key.slice(0, space);
+  const path = key.slice(space + 1);
+
+  let group = "api";
+  if (resourceKeys.has(key)) group = "resource";
+  else if (customKeys.has(key)) group = "custom";
+  else if (path.startsWith("/api/auth")) group = "auth";
+  else if (path.includes("notifications")) group = "notifications";
+  else if (path === "/health" || path === "/ready" || path === "/api/health" || path === "/api/ready") {
+    group = "probe";
+  } else if (path.startsWith("/api/dev")) group = "dev";
+
+  return { method, path, group };
+}

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

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "vitest";
+import {
+  string,
+  number,
+  email,
+  select,
+  date,
+  belongsTo,
+  hasMany,
+  belongsToMany,
+  resolveFields,
+  foreignKeyFor,
+  pivotTableFor,
+} from "./fields.js";
+import { checkPolicy, policyFromRole } from "./policy.js";
+
+describe("fields", () => {
+  test("string required", () => {
+    const fields = resolveFields({ name: string().required() });
+    expect(fields.name.required).toBe(true);
+    expect(fields.name.type).toBe("string");
+  });
+
+  test("belongsTo sets relation column", () => {
+    const fields = resolveFields({ category: belongsTo("categories") });
+    expect(fields.category.type).toBe("relation");
+    expect(fields.category.column).toBe("category_id");
+    expect(fields.category.relation).toBe("categories");
+  });
+
+  test("belongsTo field ending with _id does not double suffix", () => {
+    const fields = resolveFields({ teacher_id: belongsTo("teachers") });
+    expect(fields.teacher_id.column).toBe("teacher_id");
+  });
+
+  test("reserved field name throws clear error", () => {
+    expect(() => resolveFields({ order: number() })).toThrow(/reserved word/);
+  });
+
+  test("hasMany sets relation mode", () => {
+    const fields = resolveFields({ items: hasMany("order_items") });
+    expect(fields.items.type).toBe("hasMany");
+    expect(fields.items.relation).toBe("order_items");
+  });
+
+  test("foreignKeyFor parent table", () => {
+    expect(foreignKeyFor("orders")).toBe("order_id");
+    expect(foreignKeyFor("clients")).toBe("client_id");
+  });
+
+  test("number min max", () => {
+    const fields = resolveFields({ age: number().min(1).max(100) });
+    expect(fields.age.min).toBe(1);
+    expect(fields.age.max).toBe(100);
+  });
+
+  test("email type", () => {
+    const fields = resolveFields({ mail: email().required() });
+    expect(fields.mail.type).toBe("email");
+  });
+
+  test("belongsToMany pivot name", () => {
+    expect(pivotTableFor("posts", "tags")).toBe("post_tag");
+    const fields = resolveFields({ tags: belongsToMany("tags") });
+    expect(fields.tags.type).toBe("belongsToMany");
+  });
+});
+
+describe("policy", () => {
+  test("policyFromRole requires role", () => {
+    const policy = policyFromRole("manager");
+    expect(checkPolicy(policy, "view", null)).toBe(false);
+    expect(checkPolicy(policy, "view", { id: 1, email: "a", role: "manager" })).toBe(true);
+  });
+
+  test("custom policy function", () => {
+    const policy = { update: (user) => user?.role === "admin" };
+    expect(checkPolicy(policy, "update", { id: 1, email: "a", role: "user" })).toBe(false);
+    expect(checkPolicy(policy, "update", { id: 1, email: "a", role: "admin" })).toBe(true);
+  });
+});