@nexa-stack/framework 1.0.0

package/packages/core/src/fields.ts

@@ -0,0 +1,309 @@
+export type FieldType =
+  | "string"
+  | "number"
+  | "boolean"
+  | "text"
+  | "email"
+  | "money"
+  | "date"
+  | "datetime"
+  | "select"
+  | "relation"
+  | "hasMany"
+  | "belongsToMany"
+  | "file"
+  | "image";
+
+export type RelationMode = "belongsTo" | "hasMany" | "belongsToMany";
+
+export interface FieldDef {
+  type: FieldType;
+  required: boolean;
+  min?: number;
+  max?: number;
+  relation?: string;
+  column?: string;
+  relationMode?: RelationMode;
+  options?: string[];
+  label?: string;
+  /** Override pivot table name for belongsToMany */
+  pivot?: string;
+}
+
+export class FieldBuilder {
+  constructor(private def: FieldDef) {}
+
+  required(): FieldBuilder {
+    return new FieldBuilder({ ...this.def, required: true });
+  }
+
+  min(n: number): FieldBuilder {
+    return new FieldBuilder({ ...this.def, min: n });
+  }
+
+  max(n: number): FieldBuilder {
+    return new FieldBuilder({ ...this.def, max: n });
+  }
+
+  label(text: string): FieldBuilder {
+    return new FieldBuilder({ ...this.def, label: text });
+  }
+
+  build(): FieldDef {
+    return this.def;
+  }
+}
+
+export function string(): FieldBuilder {
+  return new FieldBuilder({ type: "string", required: false });
+}
+
+export function number(): FieldBuilder {
+  return new FieldBuilder({ type: "number", required: false });
+}
+
+export function boolean(): FieldBuilder {
+  return new FieldBuilder({ type: "boolean", required: false });
+}
+
+export function text(): FieldBuilder {
+  return new FieldBuilder({ type: "text", required: false });
+}
+
+export function email(): FieldBuilder {
+  return new FieldBuilder({ type: "email", required: false });
+}
+
+export function money(): FieldBuilder {
+  return new FieldBuilder({ type: "money", required: false });
+}
+
+export function date(): FieldBuilder {
+  return new FieldBuilder({ type: "date", required: false });
+}
+
+export function datetime(): FieldBuilder {
+  return new FieldBuilder({ type: "datetime", required: false });
+}
+
+/** Dropdown — options are plain strings stored as TEXT */
+export function select(options: string[]): FieldBuilder {
+  return new FieldBuilder({ type: "select", required: false, options: [...options] });
+}
+
+export function file(): FieldBuilder {
+  return new FieldBuilder({ type: "file", required: false });
+}
+
+export function image(): FieldBuilder {
+  return new FieldBuilder({ type: "image", required: false });
+}
+
+export function belongsTo(target: string): FieldBuilder {
+  return new FieldBuilder({
+    type: "relation",
+    required: false,
+    relation: target.toLowerCase(),
+    relationMode: "belongsTo",
+  });
+}
+
+export function hasMany(target: string): FieldBuilder {
+  return new FieldBuilder({
+    type: "hasMany",
+    required: false,
+    relation: target.toLowerCase(),
+    relationMode: "hasMany",
+  });
+}
+
+/** Many-to-many — auto pivot table (e.g. posts + tags → post_tag) */
+export function belongsToMany(target: string, pivot?: string): FieldBuilder {
+  return new FieldBuilder({
+    type: "belongsToMany",
+    required: false,
+    relation: target.toLowerCase(),
+    relationMode: "belongsToMany",
+    pivot: pivot?.toLowerCase(),
+  });
+}
+
+const SQL_RESERVED = new Set(
+  [
+    "abort",
+    "action",
+    "add",
+    "after",
+    "all",
+    "alter",
+    "analyze",
+    "and",
+    "as",
+    "asc",
+    "attach",
+    "autoincrement",
+    "before",
+    "begin",
+    "between",
+    "by",
+    "cascade",
+    "case",
+    "cast",
+    "check",
+    "collate",
+    "column",
+    "commit",
+    "conflict",
+    "constraint",
+    "create",
+    "cross",
+    "current_date",
+    "current_time",
+    "current_timestamp",
+    "database",
+    "default",
+    "deferrable",
+    "deferred",
+    "delete",
+    "desc",
+    "detach",
+    "distinct",
+    "drop",
+    "each",
+    "else",
+    "end",
+    "escape",
+    "except",
+    "exclusive",
+    "exists",
+    "explain",
+    "fail",
+    "for",
+    "foreign",
+    "from",
+    "full",
+    "glob",
+    "group",
+    "having",
+    "if",
+    "ignore",
+    "immediate",
+    "in",
+    "index",
+    "indexed",
+    "initially",
+    "inner",
+    "insert",
+    "instead",
+    "intersect",
+    "into",
+    "is",
+    "isnull",
+    "join",
+    "key",
+    "left",
+    "like",
+    "limit",
+    "match",
+    "natural",
+    "no",
+    "not",
+    "notnull",
+    "null",
+    "of",
+    "offset",
+    "on",
+    "or",
+    "order",
+    "outer",
+    "plan",
+    "pragma",
+    "primary",
+    "query",
+    "raise",
+    "recursive",
+    "references",
+    "regexp",
+    "reindex",
+    "release",
+    "rename",
+    "replace",
+    "restrict",
+    "right",
+    "rollback",
+    "row",
+    "savepoint",
+    "select",
+    "set",
+    "table",
+    "temp",
+    "temporary",
+    "then",
+    "to",
+    "transaction",
+    "trigger",
+    "union",
+    "unique",
+    "update",
+    "using",
+    "vacuum",
+    "values",
+    "view",
+    "virtual",
+    "when",
+    "where",
+    "with",
+    "without",
+  ].map((w) => w.toLowerCase())
+);
+
+export function relationColumnName(fieldName: string): string {
+  const base = fieldName.endsWith("_id") ? fieldName.slice(0, -3) : fieldName;
+  return `${base}_id`;
+}
+
+export function resolveFields(
+  fields: Record<string, FieldBuilder>
+): Record<string, FieldDef> {
+  const resolved: Record<string, FieldDef> = {};
+  for (const [name, builder] of Object.entries(fields)) {
+    if (SQL_RESERVED.has(name.toLowerCase())) {
+      throw new Error(
+        `Field name "${name}" is a SQL reserved word. Rename it (e.g. lesson_order instead of order).`
+      );
+    }
+    const def = builder.build();
+    if (def.type === "relation" && !def.column) {
+      def.column = relationColumnName(name);
+    }
+    resolved[name] = def;
+  }
+  return resolved;
+}
+
+export function fieldColumn(name: string, field: FieldDef): string | null {
+  if (field.type === "hasMany" || field.type === "belongsToMany") return null;
+  if (field.type === "relation") return field.column ?? relationColumnName(name);
+  return name;
+}
+
+export function isStoredField(field: FieldDef): boolean {
+  return field.type !== "hasMany" && field.type !== "belongsToMany";
+}
+
+export function singularize(table: string): string {
+  const t = table.toLowerCase();
+  if (t.endsWith("ies") && t.length > 3) return `${t.slice(0, -3)}y`;
+  if (t.endsWith("ses")) return t.slice(0, -2);
+  if (t.endsWith("s") && t.length > 1) return t.slice(0, -1);
+  return t;
+}
+
+export function foreignKeyFor(parentTable: string): string {
+  return `${singularize(parentTable)}_id`;
+}
+
+/** Alphabetical pivot table: posts + tags → post_tag */
+export function pivotTableFor(a: string, b: string): string {
+  return [singularize(a), singularize(b)].sort().join("_");
+}

package/packages/core/src/index.ts

@@ -0,0 +1,60 @@
+export { resource, type Resource, type ResourceDefinition } from "./resource.js";
+export {
+  string,
+  number,
+  boolean,
+  text,
+  email,
+  money,
+  date,
+  datetime,
+  select,
+  belongsTo,
+  hasMany,
+  belongsToMany,
+  file,
+  image,
+  type FieldDef,
+  FieldBuilder,
+} from "./fields.js";
+export { loadResources } from "./loader.js";
+export {
+  checkPolicy,
+  policyFromRole,
+  type PolicyAction,
+  type PolicyRule,
+  type ResourcePolicy,
+} from "./policy.js";
+export { start, db, connect, serve, getDb } from "./app.js";
+export { route, clearCustomRoutes, type RouteHandler } from "./routes.js";
+export { runMigrations, rollbackMigrations, runSeeders } from "./migrate.js";
+export { QueryBuilder } from "../../database/src/builder.js";
+export { createClient } from "../../client/src/index.js";
+export { setupAuth, seedAdmin, login, register, signToken, verifyToken, hasRole } from "../../auth/src/index.js";
+export { config, loadEnv } from "./config.js";
+export { on, emit, clearEvents } from "../../events/src/index.js";
+export { setupQueue, dispatch, processJobs, registerBuiltInJobs, workQueue } from "../../queue/src/index.js";
+export { saveUpload, ensureStorage } from "../../storage/src/upload.js";
+export { Mail, mail, sendMail } from "../../mail/src/index.js";
+export {
+  notify,
+  setupNotifications,
+  unreadNotifications,
+  markNotificationRead,
+  markAllRead,
+} from "../../notifications/src/index.js";
+export { cache } from "../../cache/src/index.js";
+export { log } from "../../log/src/index.js";
+export { schedule, runDueTasks, startScheduler, stopScheduler } from "../../schedule/src/index.js";
+export { sms } from "../../sms/src/index.js";
+export { toCsv, exportResponse } from "../../export/src/index.js";
+export { plugin, bootPlugins, hook, listPlugins, clearPlugins } from "../../plugins/src/index.js";
+export { use, rateLimit, cors, clearMiddleware } from "../../server/src/middleware.js";
+export { createTestApp } from "../../testing/src/index.js";
+export {
+  forgotPassword,
+  resetPassword,
+  verifyEmail,
+  resendVerification,
+  sendVerificationEmail,
+} from "../../auth/src/auth.js";

package/packages/core/src/lang.ts

@@ -0,0 +1,79 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { config } from "./config.js";
+
+type LangData = Record<string, string | Record<string, string>>;
+
+const cache = new Map<string, LangData>();
+
+const defaultUi: Record<string, string> = {
+  title: "Nexa",
+  dashboard: "Dashboard",
+  login: "Login",
+  logout: "Logout",
+  add: "Add",
+  delete: "Delete",
+  empty: "No data",
+  confirm_delete: "Delete?",
+};
+
+/** When a locale file is missing, fall back to APP_LOCALE then English. */
+function fallbackLocale(locale: string): string {
+  const preferred = config("APP_LOCALE") || "en";
+  if (locale !== preferred) return preferred;
+  return "en";
+}
+
+export function loadLang(locale: string, root = process.cwd()): LangData {
+  const key = `${root}:${locale}`;
+  if (cache.has(key)) return cache.get(key)!;
+
+  const file = join(root, "lang", `${locale}.json`);
+  if (existsSync(file)) {
+    const data = JSON.parse(readFileSync(file, "utf-8")) as LangData;
+    cache.set(key, data);
+    return data;
+  }
+
+  const alt = fallbackLocale(locale);
+  if (alt !== locale) {
+    const altFile = join(root, "lang", `${alt}.json`);
+    if (existsSync(altFile)) {
+      const data = JSON.parse(readFileSync(altFile, "utf-8")) as LangData;
+      cache.set(key, data);
+      return data;
+    }
+  }
+
+  const data: LangData = { ui: { ...defaultUi } };
+  cache.set(key, data);
+  return data;
+}
+
+export function clearLangCache(): void {
+  cache.clear();
+}
+
+export function t(key: string, locale = "en", root = process.cwd()): string {
+  const data = loadLang(locale, root);
+  const val = data[key];
+  return typeof val === "string" ? val : key;
+}
+
+export function ui(key: string, locale = "en", root = process.cwd()): string {
+  const data = loadLang(locale, root);
+  const uiBlock = data.ui;
+  if (typeof uiBlock === "object" && key in uiBlock) return uiBlock[key];
+  return defaultUi[key] ?? key;
+}
+
+export function getUi(locale = "en", root = process.cwd()): Record<string, string> {
+  const data = loadLang(locale, root);
+  const uiBlock = data.ui;
+  if (typeof uiBlock === "object") return { ...defaultUi, ...uiBlock };
+  return { ...defaultUi };
+}
+
+export function defaultLocale(): string {
+  return config("APP_LOCALE") || "en";
+}

package/packages/core/src/loader.ts

@@ -0,0 +1,42 @@
+import { readFileSync, writeFileSync, unlinkSync, readdirSync } from "fs";
+import { join, dirname, basename } from "path";
+import { pathToFileURL } from "url";
+
+/** Import a TS file in a fresh module context (Bun ignores ?query cache bust). */
+export async function importFreshTs(absPath: string): Promise<void> {
+  const dir = dirname(absPath);
+  const shadow = join(dir, `.nexa-reload-${Date.now()}-${basename(absPath)}`);
+  writeFileSync(shadow, readFileSync(absPath, "utf8"));
+  try {
+    await import(pathToFileURL(shadow).href);
+  } finally {
+    try {
+      unlinkSync(shadow);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/** Auto-import every `resources/*.ts` so you never wire them in app.ts */
+export async function loadResources(
+  cwd = process.cwd(),
+  opts?: { reload?: boolean }
+): Promise<number> {
+  const dir = join(cwd, "resources");
+  let files: string[] = [];
+  try {
+    files = readdirSync(dir)
+      .filter((f) => f.endsWith(".ts") && !f.startsWith(".nexa-reload-"))
+      .sort();
+  } catch {
+    return 0;
+  }
+
+  for (const file of files) {
+    const abs = join(dir, file);
+    if (opts?.reload) await importFreshTs(abs);
+    else await import(pathToFileURL(abs).href);
+  }
+  return files.length;
+}

package/packages/core/src/migrate.ts

@@ -0,0 +1,91 @@
+import { join } from "path";
+import { readdirSync } from "fs";
+import { getResources } from "./registry.js";
+import { createDatabase, type Database } from "../../database/src/index.js";
+import { migrationsTableSql } from "../../database/src/dialect.js";
+
+export async function runMigrations(dbPath: string): Promise<Database> {
+  const db = createDatabase(dbPath);
+  await db.connect();
+
+  await db.run(migrationsTableSql(db.dialect));
+
+  for (const def of getResources()) {
+    await db.createTable(def);
+  }
+
+  const dir = join(process.cwd(), "database", "migrations");
+  let files: string[] = [];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".ts")).sort();
+  } catch {
+    /* no migrations folder */
+  }
+
+  for (const file of files) {
+    const name = file.replace(/\.ts$/, "");
+    const ran = await db.getOne("SELECT id FROM _nexa_migrations WHERE name = ?", [name]);
+    if (ran) continue;
+
+    const mod = await import(new URL(`file:///${dir.replace(/\\/g, "/")}/${file}`).href);
+    if (mod.up) await mod.up(db);
+    await db.run("INSERT INTO _nexa_migrations (name) VALUES (?)", [name]);
+    console.log(`Migrated: ${name}`);
+  }
+
+  console.log("Migrations complete");
+  return db;
+}
+
+/** Create / sync tables for all registered resources (hot reload). */
+export async function syncResourceTables(db: Database): Promise<void> {
+  for (const def of getResources()) {
+    await db.createTable(def);
+    await db.syncColumns(def);
+  }
+}
+
+/** Roll back the last N file migrations that define `down` */
+export async function rollbackMigrations(db: Database, steps = 1): Promise<number> {
+  const rows = await db.query(
+    `SELECT name FROM _nexa_migrations ORDER BY id DESC LIMIT ?`,
+    [steps]
+  );
+  const dir = join(process.cwd(), "database", "migrations").replace(/\\/g, "/");
+  let done = 0;
+  for (const row of rows) {
+    const name = String(row.name);
+    try {
+      const mod = await import(new URL(`file:///${dir}/${name}.ts`).href);
+      if (mod.down) {
+        await mod.down(db);
+        await db.run(`DELETE FROM _nexa_migrations WHERE name = ?`, [name]);
+        console.log(`Rolled back: ${name}`);
+        done++;
+      } else {
+        console.log(`Skip rollback (no down): ${name}`);
+      }
+    } catch (e) {
+      console.error(`Rollback failed: ${name}`, e);
+      break;
+    }
+  }
+  return done;
+}
+
+export async function runSeeders(db: Database): Promise<void> {
+  const dir = join(process.cwd(), "database", "seeders");
+  let files: string[] = [];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".ts")).sort();
+  } catch {
+    return;
+  }
+
+  for (const file of files) {
+    const mod = await import(new URL(`file:///${dir.replace(/\\/g, "/")}/${file}`).href);
+    if (mod.default) await mod.default(db);
+    else if (mod.seed) await mod.seed(db);
+    console.log(`Seeded: ${file}`);
+  }
+}

package/packages/core/src/policy.ts

@@ -0,0 +1,36 @@
+import type { AuthUser } from "../../auth/src/auth.js";
+import { hasRole } from "../../auth/src/auth.js";
+
+export type PolicyAction = "view" | "create" | "update" | "delete";
+export type PolicyRule = string | ((user: AuthUser | null, item?: Record<string, unknown>) => boolean);
+
+export interface ResourcePolicy {
+  view?: PolicyRule;
+  create?: PolicyRule;
+  update?: PolicyRule;
+  delete?: PolicyRule;
+}
+
+export function checkPolicy(
+  policy: ResourcePolicy | null,
+  action: PolicyAction,
+  user: AuthUser | null,
+  item?: Record<string, unknown>
+): boolean {
+  if (!policy) return true;
+
+  const rule = policy[action];
+  if (!rule) return true;
+
+  if (typeof rule === "string") return hasRole(user, rule);
+  return rule(user, item);
+}
+
+export function policyFromRole(role: string): ResourcePolicy {
+  return {
+    view: role,
+    create: role,
+    update: role,
+    delete: role,
+  };
+}

package/packages/core/src/registry.ts

@@ -0,0 +1,17 @@
+import type { ResourceDefinition } from "./resource.js";
+
+const registry: ResourceDefinition[] = [];
+
+export function registerResource(def: ResourceDefinition): void {
+  const i = registry.findIndex((r) => r.name === def.name);
+  if (i >= 0) registry[i] = def;
+  else registry.push(def);
+}
+
+export function getResources(): ResourceDefinition[] {
+  return registry;
+}
+
+export function clearRegistry(): void {
+  registry.length = 0;
+}