@nexa-stack/framework 1.0.0

package/packages/database/src/query.ts

@@ -0,0 +1,115 @@
+export interface QueryOpts {
+  limit?: number;
+  offset?: number;
+  search?: string;
+  searchFields?: string[];
+  filters?: Record<string, string>;
+  sort?: string;
+  order?: "asc" | "desc";
+  /** Soft deletes: exclude = active only (default for soft resources), only = trash, with = all */
+  softDelete?: "exclude" | "only" | "with";
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  meta: {
+    current_page: number;
+    from: number | null;
+    last_page: number;
+    per_page: number;
+    to: number | null;
+    total: number;
+  };
+  links: {
+    first: string | null;
+    last: string | null;
+    prev: string | null;
+    next: string | null;
+  };
+}
+
+const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/** Reject anything that is not a plain SQL identifier */
+export function safeIdent(name: string, fallback = "id"): string {
+  return IDENT_RE.test(name) ? name : fallback;
+}
+
+export function buildQuery(
+  table: string,
+  opts: QueryOpts
+): { sql: string; countSql: string; params: unknown[] } {
+  const tableName = safeIdent(table, "");
+  if (!tableName) throw new Error("Invalid table name");
+
+  const params: unknown[] = [];
+  const conditions: string[] = [];
+
+  if (opts.search && opts.searchFields?.length) {
+    const fields = opts.searchFields.map((f) => safeIdent(f, "")).filter(Boolean);
+    if (fields.length) {
+      const parts = fields.map((f) => `${f} LIKE ?`);
+      conditions.push(`(${parts.join(" OR ")})`);
+      for (const _ of fields) params.push(`%${opts.search}%`);
+    }
+  }
+
+  if (opts.filters) {
+    for (const [key, val] of Object.entries(opts.filters)) {
+      if (val === "" || val == null) continue;
+      const col = safeIdent(key, "");
+      if (!col) continue;
+      conditions.push(`${col} = ?`);
+      params.push(val);
+    }
+  }
+
+  if (opts.softDelete === "exclude") {
+    conditions.push("(deleted_at IS NULL OR deleted_at = '')");
+  } else if (opts.softDelete === "only") {
+    conditions.push("(deleted_at IS NOT NULL AND deleted_at != '')");
+  }
+
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  const sortCol = safeIdent(opts.sort ?? "id", "id");
+  const sortOrder = opts.order === "asc" ? "ASC" : "DESC";
+  const limit = opts.limit ?? 20;
+  const offset = opts.offset ?? 0;
+
+  const sql = `SELECT * FROM ${tableName} ${where} ORDER BY ${sortCol} ${sortOrder} LIMIT ? OFFSET ?`;
+  const countSql = `SELECT COUNT(*) as total FROM ${tableName} ${where}`;
+
+  return { sql, countSql, params: [...params, limit, offset] };
+}
+
+export function paginate<T extends { id?: unknown }>(
+  items: T[],
+  total: number,
+  page: number,
+  perPage: number,
+  baseUrl: string
+): PaginatedResult<T> {
+  const lastPage = Math.max(1, Math.ceil(total / perPage));
+  const from = total === 0 ? null : (page - 1) * perPage + 1;
+  const to = total === 0 ? null : from! + items.length - 1;
+
+  const link = (p: number) => `${baseUrl}?page=${p}&limit=${perPage}`;
+
+  return {
+    data: items,
+    meta: {
+      current_page: page,
+      from,
+      last_page: lastPage,
+      per_page: perPage,
+      to,
+      total,
+    },
+    links: {
+      first: link(1),
+      last: link(lastPage),
+      prev: page > 1 ? link(page - 1) : null,
+      next: page < lastPage ? link(page + 1) : null,
+    },
+  };
+}

package/packages/database/src/sqlite.ts

@@ -0,0 +1,216 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+import { createRequire } from "module";
+import type { ResourceDefinition } from "../../core/src/resource.js";
+import { fieldColumn } from "../../core/src/fields.js";
+import type { QueryOpts } from "./query.js";
+import { buildQuery } from "./query.js";
+import type { DatabaseDriver, DbRow } from "./types.js";
+import { buildColumns } from "./types.js";
+
+type SqlJsDatabase = {
+  run: (sql: string, params?: unknown[]) => void;
+  exec: (sql: string) => { columns: string[]; values: unknown[][] }[];
+  prepare: (sql: string) => {
+    bind: (params: unknown[]) => void;
+    step: () => boolean;
+    getAsObject: () => Record<string, unknown>;
+    free: () => void;
+  };
+  export: () => Uint8Array;
+  close: () => void;
+};
+
+function bindValue(v: unknown): unknown {
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (v === undefined) return null;
+  return v;
+}
+
+function bindParams(params: unknown[]): unknown[] {
+  return params.map(bindValue);
+}
+
+/**
+ * SQLite via sql.js (WASM) — no Visual Studio / node-gyp / native build.
+ * Fine for local + small apps. On Hostinger prefer MySQL via DATABASE_URL.
+ */
+export class SqliteDriver implements DatabaseDriver {
+  readonly dialect = "sqlite" as const;
+  private db: SqlJsDatabase | null = null;
+  private dirty = false;
+
+  constructor(private path: string) {}
+
+  async connect(): Promise<void> {
+    const initSqlJs = (await import("sql.js")).default;
+    const require = createRequire(import.meta.url);
+    const distDir = dirname(require.resolve("sql.js"));
+    const SQL = await initSqlJs({
+      locateFile: (file: string) => join(distDir, file),
+    });
+
+    if (this.path === ":memory:" || !existsSync(this.path)) {
+      this.db = new SQL.Database() as SqlJsDatabase;
+      if (this.path !== ":memory:") {
+        mkdirSync(dirname(this.path), { recursive: true });
+        this.dirty = true;
+        this.persist();
+      }
+    } else {
+      const fileBuffer = readFileSync(this.path);
+      this.db = new SQL.Database(fileBuffer) as SqlJsDatabase;
+    }
+
+    this.db.run("PRAGMA foreign_keys = ON");
+  }
+
+  private assertDb(): SqlJsDatabase {
+    if (!this.db) throw new Error("SQLite not connected");
+    return this.db;
+  }
+
+  private persist(): void {
+    if (!this.db || this.path === ":memory:" || !this.dirty) return;
+    writeFileSync(this.path, Buffer.from(this.db.export()));
+    this.dirty = false;
+  }
+
+  private markDirty(): void {
+    this.dirty = true;
+    this.persist();
+  }
+
+  private all(sql: string, params: unknown[] = []): DbRow[] {
+    const db = this.assertDb();
+    const stmt = db.prepare(sql);
+    try {
+      if (params.length) stmt.bind(bindParams(params));
+      const rows: DbRow[] = [];
+      while (stmt.step()) {
+        rows.push(stmt.getAsObject() as DbRow);
+      }
+      return rows;
+    } finally {
+      stmt.free();
+    }
+  }
+
+  private one(sql: string, params: unknown[] = []): DbRow | null {
+    return this.all(sql, params)[0] ?? null;
+  }
+
+  async createTable(resource: ResourceDefinition): Promise<void> {
+    const db = this.assertDb();
+    const columns = buildColumns(resource);
+    db.run(`
+      CREATE TABLE IF NOT EXISTS ${resource.table} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ${columns ? `${columns},` : ""}
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      )
+    `);
+    this.markDirty();
+  }
+
+  findAll(table: string, opts: QueryOpts = {}): DbRow[] {
+    if (!opts.search && !opts.filters && !opts.sort && !opts.softDelete) {
+      const limit = opts.limit ?? 100;
+      const offset = opts.offset ?? 0;
+      return this.all(`SELECT * FROM ${table} ORDER BY id DESC LIMIT ? OFFSET ?`, [
+        limit,
+        offset,
+      ]);
+    }
+    const { sql, params } = buildQuery(table, opts);
+    return this.all(sql, params);
+  }
+
+  count(table: string, opts: QueryOpts = {}): number {
+    if (!opts.search && !opts.filters && !opts.softDelete) {
+      const row = this.one(`SELECT COUNT(*) as total FROM ${table}`);
+      return Number(row?.total ?? 0);
+    }
+    const { countSql, params } = buildQuery(table, { ...opts, limit: 1, offset: 0 });
+    const row = this.one(countSql, params.slice(0, -2));
+    return Number(row?.total ?? 0);
+  }
+
+  findById(table: string, id: number): DbRow | null {
+    return this.one(`SELECT * FROM ${table} WHERE id = ?`, [id]);
+  }
+
+  insert(table: string, data: Record<string, unknown>): DbRow {
+    const db = this.assertDb();
+    const keys = Object.keys(data);
+    const placeholders = keys.map(() => "?").join(", ");
+    const values = keys.map((k) => bindValue(data[k]));
+    try {
+      const row = this.one(
+        `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders}) RETURNING *`,
+        values
+      );
+      this.markDirty();
+      if (row) return row;
+    } catch {
+      /* older sql.js / no RETURNING — fallback */
+    }
+    db.run(
+      `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders})`,
+      values
+    );
+    this.markDirty();
+    const idRow = this.one(`SELECT last_insert_rowid() as id`);
+    const id = Number(idRow?.id ?? 0);
+    return this.findById(table, id) ?? { id, ...data };
+  }
+
+  update(table: string, id: number, data: Record<string, unknown>): DbRow | null {
+    const db = this.assertDb();
+    const keys = Object.keys(data);
+    if (keys.length === 0) return this.findById(table, id);
+    const setClause = keys.map((k) => `${k} = ?`).join(", ");
+    db.run(`UPDATE ${table} SET ${setClause}, updated_at = datetime('now') WHERE id = ?`, [
+      ...keys.map((k) => bindValue(data[k])),
+      id,
+    ]);
+    this.markDirty();
+    return this.findById(table, id);
+  }
+
+  delete(table: string, id: number): boolean {
+    const before = this.findById(table, id);
+    if (!before) return false;
+    this.assertDb().run(`DELETE FROM ${table} WHERE id = ?`, [id]);
+    this.markDirty();
+    return true;
+  }
+
+  query(sql: string, params: unknown[] = []): DbRow[] {
+    return this.all(sql, params);
+  }
+
+  getOne(sql: string, params: unknown[] = []): DbRow | null {
+    return this.one(sql, params);
+  }
+
+  run(sql: string, params: unknown[] = []): void {
+    this.assertDb().run(sql, bindParams(params));
+    this.markDirty();
+  }
+
+  close(): void {
+    if (this.db) {
+      this.persist();
+      this.db.close();
+      this.db = null;
+    }
+  }
+}
+
+export function searchFieldsFor(resource: ResourceDefinition): string[] {
+  return Object.entries(resource.fields)
+    .filter(([, f]) => f.type === "string" || f.type === "email" || f.type === "text")
+    .map(([name, f]) => fieldColumn(name, f));
+}

package/packages/database/src/types.ts

@@ -0,0 +1,104 @@
+import type { FieldDef } from "../../core/src/fields.js";
+import { fieldColumn, isStoredField } from "../../core/src/fields.js";
+import type { ResourceDefinition } from "../../core/src/resource.js";
+import type { QueryOpts } from "./query.js";
+
+export type { QueryOpts };
+
+export interface DbRow {
+  [key: string]: unknown;
+}
+
+export type DbDialect = "sqlite" | "postgres" | "mysql";
+
+export interface DatabaseDriver {
+  dialect: DbDialect;
+  connect(): Promise<void>;
+  createTable(resource: ResourceDefinition): Promise<void>;
+  findAll(table: string, opts?: QueryOpts): DbRow[] | Promise<DbRow[]>;
+  count(table: string, opts?: QueryOpts): number | Promise<number>;
+  findById(table: string, id: number): DbRow | null | Promise<DbRow | null>;
+  insert(table: string, data: Record<string, unknown>): DbRow | Promise<DbRow>;
+  update(
+    table: string,
+    id: number,
+    data: Record<string, unknown>
+  ): DbRow | null | Promise<DbRow | null>;
+  delete(table: string, id: number): boolean | Promise<boolean>;
+  query(sql: string, params?: unknown[]): DbRow[] | Promise<DbRow[]>;
+  getOne(sql: string, params?: unknown[]): DbRow | null | Promise<DbRow | null>;
+  run(sql: string, params?: unknown[]): void | Promise<void>;
+  close(): void;
+}
+
+export function buildColumns(resource: ResourceDefinition): string {
+  const cols = Object.entries(resource.fields)
+    .filter(([, field]) => isStoredField(field))
+    .map(([name, field]) => `${fieldColumn(name, field!)} ${sqlType(field)}`);
+  if (resource.softDelete) cols.push("deleted_at TEXT");
+  return cols.join(", ");
+}
+
+export function buildPgColumns(resource: ResourceDefinition): string {
+  const cols = Object.entries(resource.fields)
+    .filter(([, field]) => isStoredField(field))
+    .map(([name, field]) => `${fieldColumn(name, field!)} ${pgSqlType(field)}`);
+  if (resource.softDelete) cols.push("deleted_at TIMESTAMPTZ");
+  return cols.join(", ");
+}
+
+export function buildMySqlColumns(resource: ResourceDefinition): string {
+  const cols = Object.entries(resource.fields)
+    .filter(([, field]) => isStoredField(field))
+    .map(([name, field]) => `\`${fieldColumn(name, field!)}\` ${mySqlType(field)}`);
+  if (resource.softDelete) cols.push("`deleted_at` VARCHAR(50) NULL");
+  return cols.join(", ");
+}
+
+function sqlType(field: FieldDef): string {
+  switch (field.type) {
+    case "number":
+    case "money":
+      return "REAL";
+    case "boolean":
+      return "INTEGER";
+    case "relation":
+      return "INTEGER";
+    case "file":
+    case "image":
+      return "TEXT";
+    default:
+      return "TEXT";
+  }
+}
+
+export function pgSqlType(field: FieldDef): string {
+  switch (field.type) {
+    case "number":
+    case "money":
+      return "DOUBLE PRECISION";
+    case "boolean":
+      return "BOOLEAN";
+    case "relation":
+      return "INTEGER";
+    default:
+      return "TEXT";
+  }
+}
+
+export function mySqlType(field: FieldDef): string {
+  switch (field.type) {
+    case "number":
+    case "money":
+      return "DOUBLE";
+    case "boolean":
+      return "TINYINT(1)";
+    case "relation":
+      return "INT";
+    default:
+      return "TEXT";
+  }
+}
+
+export { sqlType };
+

package/packages/events/src/index.ts

@@ -0,0 +1,17 @@
+type Handler = (payload: unknown) => void | Promise<void>;
+
+const handlers = new Map<string, Handler[]>();
+
+export function on(event: string, handler: Handler): void {
+  if (!handlers.has(event)) handlers.set(event, []);
+  handlers.get(event)!.push(handler);
+}
+
+export async function emit(event: string, payload: unknown): Promise<void> {
+  const list = handlers.get(event) ?? [];
+  for (const fn of list) await fn(payload);
+}
+
+export function clearEvents(): void {
+  handlers.clear();
+}

package/packages/export/src/index.ts

@@ -0,0 +1,36 @@
+export function toCsv(rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) return "";
+  const keys = Object.keys(rows[0]);
+  const escape = (v: unknown) => {
+    const s = v == null ? "" : String(v);
+    if (/[",\n]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
+    return s;
+  };
+  const lines = [keys.join(",")];
+  for (const row of rows) {
+    lines.push(keys.map((k) => escape(row[k])).join(","));
+  }
+  return lines.join("\n");
+}
+
+export function exportResponse(
+  rows: Record<string, unknown>[],
+  format: "csv" | "json",
+  filename: string
+): Response {
+  if (format === "json") {
+    return new Response(JSON.stringify({ data: rows }, null, 2), {
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Disposition": `attachment; filename="${filename}.json"`,
+      },
+    });
+  }
+  const csv = toCsv(rows);
+  return new Response(csv, {
+    headers: {
+      "Content-Type": "text/csv; charset=utf-8",
+      "Content-Disposition": `attachment; filename="${filename}.csv"`,
+    },
+  });
+}

package/packages/log/src/index.ts

@@ -0,0 +1,38 @@
+import { mkdirSync, appendFileSync, existsSync } from "fs";
+import { join } from "path";
+import { config } from "../../core/src/config.js";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+function logDir(): string {
+  const dir = join(process.cwd(), "storage", "logs");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function shouldLog(level: LogLevel): boolean {
+  const min = (config("LOG_LEVEL") || "debug") as LogLevel;
+  return LEVELS[level] >= (LEVELS[min] ?? 0);
+}
+
+function write(level: LogLevel, message: string, extra?: unknown): void {
+  if (!shouldLog(level)) return;
+  const line = `[${new Date().toISOString()}] ${level.toUpperCase()}: ${message}${
+    extra !== undefined ? " " + JSON.stringify(extra) : ""
+  }\n`;
+  process.stdout.write(line);
+  try {
+    appendFileSync(join(logDir(), "nexa.log"), line);
+  } catch {
+    /* ignore file errors */
+  }
+}
+
+export const log = {
+  debug: (msg: string, extra?: unknown) => write("debug", msg, extra),
+  info: (msg: string, extra?: unknown) => write("info", msg, extra),
+  warn: (msg: string, extra?: unknown) => write("warn", msg, extra),
+  error: (msg: string, extra?: unknown) => write("error", msg, extra),
+};

package/packages/mail/src/index.ts

@@ -0,0 +1,130 @@
+import { appendFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { config } from "../../core/src/config.js";
+import { log } from "../../log/src/index.js";
+import type { Database } from "../../database/src/database.js";
+import { dispatch } from "../../queue/src/index.js";
+
+export interface MailMessage {
+  to: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  from?: string;
+}
+
+class MailBuilder {
+  private _to: string[] = [];
+  private _subject = "";
+  private _html = "";
+  private _text = "";
+  private _from?: string;
+
+  to(address: string | string[]): this {
+    this._to = Array.isArray(address) ? address : [address];
+    return this;
+  }
+
+  subject(s: string): this {
+    this._subject = s;
+    return this;
+  }
+
+  html(body: string): this {
+    this._html = body;
+    return this;
+  }
+
+  text(body: string): this {
+    this._text = body;
+    return this;
+  }
+
+  from(address: string): this {
+    this._from = address;
+    return this;
+  }
+
+  async send(): Promise<void> {
+    await sendMail({
+      to: this._to,
+      subject: this._subject,
+      html: this._html || undefined,
+      text: this._text || undefined,
+      from: this._from,
+    });
+  }
+
+  async queue(db: Database): Promise<number> {
+    return dispatch(db, "mail.send", {
+      to: this._to,
+      subject: this._subject,
+      html: this._html || undefined,
+      text: this._text || undefined,
+      from: this._from,
+    });
+  }
+}
+
+export function Mail(): MailBuilder {
+  return new MailBuilder();
+}
+
+export async function mail(
+  to: string | string[],
+  subject: string,
+  body: string,
+  opts?: { html?: boolean; queue?: Database }
+): Promise<void | number> {
+  const builder = Mail().to(to).subject(subject);
+  if (opts?.html) builder.html(body);
+  else builder.text(body);
+
+  if (opts?.queue) return builder.queue(opts.queue);
+  await builder.send();
+}
+
+async function sendMail(msg: MailMessage): Promise<void> {
+  const driver = config("MAIL_DRIVER") || "log";
+  const from = msg.from || config("MAIL_FROM") || "nexa@localhost";
+  const to = Array.isArray(msg.to) ? msg.to.join(", ") : msg.to;
+
+  if (driver === "log") {
+    const dir = join(process.cwd(), "storage", "logs");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const line = `[${new Date().toISOString()}] MAIL to=${to} subject=${msg.subject}\n${msg.html || msg.text || ""}\n---\n`;
+    appendFileSync(join(dir, "mail.log"), line);
+    log.info(`Mail (log) → ${to}: ${msg.subject}`);
+    return;
+  }
+
+  if (driver === "smtp") {
+    const nodemailer = await import("nodemailer");
+    const transport = nodemailer.createTransport({
+      host: config("MAIL_HOST") || "localhost",
+      port: Number(config("MAIL_PORT") || 587),
+      secure: config("MAIL_SECURE") === "true",
+      auth:
+        config("MAIL_USER")
+          ? { user: config("MAIL_USER"), pass: config("MAIL_PASS") }
+          : undefined,
+    });
+    await transport.sendMail({
+      from,
+      to,
+      subject: msg.subject,
+      html: msg.html,
+      text: msg.text,
+    });
+    log.info(`Mail (smtp) → ${to}: ${msg.subject}`);
+    return;
+  }
+
+  throw new Error(`Unknown MAIL_DRIVER: ${driver}`);
+}
+
+export function registerMailJobs(): void {
+  // wired via queue emit handler in app bootstrap
+}
+
+export { sendMail };