@nexa-stack/framework 1.0.0

package/packages/notifications/src/index.ts

@@ -0,0 +1,84 @@
+import type { Database } from "../../database/src/database.js";
+import { notificationsTableSql } from "../../database/src/dialect.js";
+import { mail } from "../../mail/src/index.js";
+import { log } from "../../log/src/index.js";
+
+export interface Notifiable {
+  id: number;
+  email?: string;
+}
+
+export interface NotificationPayload {
+  type?: string;
+  title: string;
+  body?: string;
+  data?: Record<string, unknown>;
+  /** channels: database (default) + mail */
+  via?: ("database" | "mail")[];
+}
+
+let dbRef: Database | null = null;
+
+export async function setupNotifications(db: Database): Promise<void> {
+  dbRef = db;
+  await db.run(notificationsTableSql(db.dialect));
+}
+
+export async function notify(
+  user: Notifiable | number,
+  payload: NotificationPayload
+): Promise<void> {
+  if (!dbRef) throw new Error("Call setupNotifications() first");
+
+  const userId = typeof user === "number" ? user : user.id;
+  const email = typeof user === "number" ? undefined : user.email;
+  const via = payload.via ?? ["database"];
+  const type = payload.type ?? "app";
+
+  if (via.includes("database")) {
+    await dbRef.insert("notifications", {
+      user_id: userId,
+      type,
+      title: payload.title,
+      body: payload.body ?? "",
+      data: JSON.stringify(payload.data ?? {}),
+      read_at: null,
+    });
+  }
+
+  if (via.includes("mail") && email) {
+    await mail(email, payload.title, payload.body ?? payload.title);
+  }
+
+  log.info(`Notify user#${userId}: ${payload.title}`);
+}
+
+export async function unreadNotifications(userId: number): Promise<Record<string, unknown>[]> {
+  if (!dbRef) return [];
+  return dbRef.query(
+    `SELECT * FROM notifications WHERE user_id = ? AND read_at IS NULL ORDER BY id DESC LIMIT 50`,
+    [userId]
+  );
+}
+
+export async function markNotificationRead(id: number, userId: number): Promise<boolean> {
+  if (!dbRef) return false;
+  const row = await dbRef.getOne(
+    `SELECT id FROM notifications WHERE id = ? AND user_id = ?`,
+    [id, userId]
+  );
+  if (!row) return false;
+  await dbRef.run(`UPDATE notifications SET read_at = ? WHERE id = ?`, [
+    new Date().toISOString(),
+    id,
+  ]);
+  return true;
+}
+
+export async function markAllRead(userId: number): Promise<void> {
+  if (!dbRef) return;
+  await dbRef.run(
+    `UPDATE notifications SET read_at = ? WHERE user_id = ? AND read_at IS NULL`,
+    [new Date().toISOString(), userId]
+  );
+}

package/packages/plugins/src/index.ts

@@ -0,0 +1,39 @@
+type Hook = (ctx: Record<string, unknown>) => void | Promise<void>;
+
+export interface Plugin {
+  name: string;
+  boot?: () => void | Promise<void>;
+  hooks?: Record<string, Hook>;
+}
+
+const plugins: Plugin[] = [];
+const hooks = new Map<string, Hook[]>();
+
+export function plugin(p: Plugin): void {
+  plugins.push(p);
+  if (p.hooks) {
+    for (const [name, fn] of Object.entries(p.hooks)) {
+      if (!hooks.has(name)) hooks.set(name, []);
+      hooks.get(name)!.push(fn);
+    }
+  }
+}
+
+export async function bootPlugins(): Promise<void> {
+  for (const p of plugins) {
+    if (p.boot) await p.boot();
+  }
+}
+
+export async function hook(name: string, ctx: Record<string, unknown> = {}): Promise<void> {
+  for (const fn of hooks.get(name) ?? []) await fn(ctx);
+}
+
+export function listPlugins(): string[] {
+  return plugins.map((p) => p.name);
+}
+
+export function clearPlugins(): void {
+  plugins.length = 0;
+  hooks.clear();
+}

package/packages/queue/src/index.ts

@@ -0,0 +1,185 @@
+import type { Database } from "../../database/src/database.js";
+import { emit } from "../../events/src/index.js";
+import { jobsTableSql } from "../../database/src/dialect.js";
+import { randomUUID } from "crypto";
+
+export interface JobRow {
+  id: number;
+  name: string;
+  payload: string;
+  status: string;
+  attempts?: number;
+  max_tries?: number;
+  available_at?: string | null;
+  locked_by?: string | null;
+}
+
+const workerId = process.env.NEXA_WORKER_ID || `w-${randomUUID().slice(0, 8)}`;
+
+export async function setupQueue(db: Database): Promise<void> {
+  await db.run(jobsTableSql(db.dialect));
+  await ensureJobColumns(db);
+}
+
+async function ensureJobColumns(db: Database): Promise<void> {
+  const cols = await db.listColumns("_nexa_jobs");
+  const have = new Set(cols.map((c) => c.toLowerCase()));
+  const add = async (name: string, sqlType: string) => {
+    if (have.has(name)) return;
+    try {
+      await db.run(`ALTER TABLE _nexa_jobs ADD COLUMN ${name} ${sqlType}`);
+      have.add(name);
+    } catch {
+      /* exists */
+    }
+  };
+  const intType = "INTEGER";
+  const textType = db.dialect === "postgres" ? "TIMESTAMPTZ" : "TEXT";
+  await add("attempts", `${intType} DEFAULT 0`);
+  await add("max_tries", `${intType} DEFAULT 3`);
+  await add("available_at", textType);
+  await add("locked_by", "TEXT");
+}
+
+export async function dispatch(
+  db: Database,
+  name: string,
+  payload: unknown,
+  opts?: { maxTries?: number; delayMs?: number }
+): Promise<number> {
+  const available =
+    opts?.delayMs && opts.delayMs > 0
+      ? new Date(Date.now() + opts.delayMs).toISOString()
+      : new Date().toISOString();
+  const row = await db.insert("_nexa_jobs", {
+    name,
+    payload: JSON.stringify(payload),
+    status: "pending",
+    attempts: 0,
+    max_tries: opts?.maxTries ?? 3,
+    available_at: available,
+    locked_by: null,
+  });
+  return Number(row.id);
+}
+
+export { registerBuiltInJobs } from "./jobs.js";
+
+function backoffMs(attempts: number): number {
+  return Math.min(60_000, 1000 * 2 ** Math.max(0, attempts - 1));
+}
+
+/** Atomically claim pending jobs — safe for multiple workers */
+async function claimJobs(db: Database, limit: number): Promise<JobRow[]> {
+  const now = new Date().toISOString();
+
+  if (db.dialect === "postgres") {
+    try {
+      return (await db.query(
+        `
+        UPDATE _nexa_jobs SET status = 'processing', locked_by = ?
+        WHERE id IN (
+          SELECT id FROM _nexa_jobs
+          WHERE status = 'pending'
+            AND (available_at IS NULL OR available_at <= ?)
+          ORDER BY id ASC
+          LIMIT ?
+          FOR UPDATE SKIP LOCKED
+        )
+        RETURNING *
+        `,
+        [workerId, now, limit]
+      )) as JobRow[];
+    } catch {
+      /* fall through to portable claim */
+    }
+  }
+
+  const candidates = (await db.query(
+    `SELECT id FROM _nexa_jobs
+     WHERE status = 'pending'
+       AND (available_at IS NULL OR available_at <= ?)
+     ORDER BY id ASC LIMIT ?`,
+    [now, limit]
+  )) as { id: number }[];
+
+  const claimed: JobRow[] = [];
+  for (const c of candidates) {
+    await db.run(
+      `UPDATE _nexa_jobs SET status = 'processing', locked_by = ?
+       WHERE id = ? AND status = 'pending'`,
+      [workerId, c.id]
+    );
+    const row = (await db.getOne(
+      `SELECT * FROM _nexa_jobs WHERE id = ? AND status = 'processing' AND locked_by = ?`,
+      [c.id, workerId]
+    )) as JobRow | null;
+    if (row) claimed.push(row);
+  }
+  return claimed;
+}
+
+async function runOne(db: Database, job: JobRow): Promise<boolean> {
+  const attempts = Number(job.attempts ?? 0) + 1;
+  const maxTries = Number(job.max_tries ?? 3);
+  try {
+    const payload = JSON.parse(job.payload);
+    await emit(job.name, payload);
+    await db.run(
+      `UPDATE _nexa_jobs SET status = 'done', attempts = ?, locked_by = NULL WHERE id = ?`,
+      [attempts, job.id]
+    );
+    return true;
+  } catch {
+    if (attempts < maxTries) {
+      const next = new Date(Date.now() + backoffMs(attempts)).toISOString();
+      await db.run(
+        `UPDATE _nexa_jobs SET status = 'pending', attempts = ?, available_at = ?, locked_by = NULL WHERE id = ?`,
+        [attempts, next, job.id]
+      );
+    } else {
+      await db.run(
+        `UPDATE _nexa_jobs SET status = 'failed', attempts = ?, locked_by = NULL WHERE id = ?`,
+        [attempts, job.id]
+      );
+    }
+    return false;
+  }
+}
+
+export async function processJobs(
+  db: Database,
+  limit = 10,
+  concurrency = Number(process.env.QUEUE_CONCURRENCY || 1)
+): Promise<number> {
+  const jobs = await claimJobs(db, limit);
+  if (jobs.length === 0) return 0;
+
+  const conc = Math.max(1, Math.min(concurrency, jobs.length));
+  let done = 0;
+
+  for (let i = 0; i < jobs.length; i += conc) {
+    const batch = jobs.slice(i, i + conc);
+    const results = await Promise.all(batch.map((job) => runOne(db, job)));
+    done += results.filter(Boolean).length;
+  }
+  return done;
+}
+
+/** Long-running worker loop for multi-instance deploys */
+export async function workQueue(
+  db: Database,
+  opts: { limit?: number; concurrency?: number; idleMs?: number; once?: boolean } = {}
+): Promise<void> {
+  const limit = opts.limit ?? 10;
+  const concurrency = opts.concurrency ?? Number(process.env.QUEUE_CONCURRENCY || 2);
+  const idleMs = opts.idleMs ?? 1000;
+  for (;;) {
+    const n = await processJobs(db, limit, concurrency);
+    if (opts.once) return;
+    if (n === 0) {
+      const { sleep } = await import("../../core/src/runtime.js");
+      await sleep(idleMs);
+    }
+  }
+}

package/packages/queue/src/jobs.ts

@@ -0,0 +1,9 @@
+import { on } from "../../events/src/index.js";
+import { sendMail, type MailMessage } from "../../mail/src/index.js";
+
+/** Register built-in queue job handlers (mail, etc.) */
+export function registerBuiltInJobs(): void {
+  on("mail.send", async (payload) => {
+    await sendMail(payload as MailMessage);
+  });
+}

package/packages/schedule/src/index.ts

@@ -0,0 +1,64 @@
+type TaskFn = () => void | Promise<void>;
+
+export interface ScheduledTask {
+  name: string;
+  intervalMs: number;
+  fn: TaskFn;
+  lastRun?: number;
+}
+
+const tasks: ScheduledTask[] = [];
+let timer: ReturnType<typeof setInterval> | null = null;
+
+function add(name: string, intervalMs: number, fn: TaskFn): void {
+  tasks.push({ name, intervalMs, fn });
+}
+
+export const schedule = {
+  everyMinute(fn: TaskFn, name = "everyMinute"): void {
+    add(name, 60_000, fn);
+  },
+  everyFiveMinutes(fn: TaskFn, name = "everyFiveMinutes"): void {
+    add(name, 5 * 60_000, fn);
+  },
+  everyHour(fn: TaskFn, name = "everyHour"): void {
+    add(name, 60 * 60_000, fn);
+  },
+  daily(fn: TaskFn, name = "daily"): void {
+    add(name, 24 * 60 * 60_000, fn);
+  },
+  every(seconds: number, fn: TaskFn, name?: string): void {
+    add(name ?? `every_${seconds}s`, seconds * 1000, fn);
+  },
+  list(): ScheduledTask[] {
+    return [...tasks];
+  },
+  clear(): void {
+    tasks.length = 0;
+  },
+};
+
+export async function runDueTasks(now = Date.now()): Promise<number> {
+  let ran = 0;
+  for (const task of tasks) {
+    if (task.lastRun && now - task.lastRun < task.intervalMs) continue;
+    await task.fn();
+    task.lastRun = now;
+    ran++;
+  }
+  return ran;
+}
+
+/** Keep process alive and run tasks on interval (for `nexa schedule:work`) */
+export function startScheduler(tickMs = 30_000): void {
+  if (timer) return;
+  timer = setInterval(() => {
+    runDueTasks().catch((err) => console.error("schedule error", err));
+  }, tickMs);
+  console.log(`Scheduler running (${tasks.length} task(s), tick ${tickMs}ms)`);
+}
+
+export function stopScheduler(): void {
+  if (timer) clearInterval(timer);
+  timer = null;
+}

package/packages/server/src/index.ts

@@ -0,0 +1 @@
+export { Router, createServer } from "./router.js";

package/packages/server/src/middleware.ts

@@ -0,0 +1,143 @@
+import type { AuthUser } from "../../auth/src/auth.js";
+import { config } from "../../core/src/config.js";
+
+export type Middleware = (
+  req: Request,
+  user: AuthUser | null,
+  next: () => Promise<Response>
+) => Promise<Response> | Response;
+
+const stack: Middleware[] = [];
+
+export function use(mw: Middleware): void {
+  stack.push(mw);
+}
+
+export function clearMiddleware(): void {
+  stack.length = 0;
+}
+
+export function getMiddleware(): Middleware[] {
+  return [...stack];
+}
+
+export async function runMiddleware(
+  req: Request,
+  user: AuthUser | null,
+  final: () => Promise<Response>
+): Promise<Response> {
+  let i = 0;
+  const dispatch = async (): Promise<Response> => {
+    if (i >= stack.length) return final();
+    const mw = stack[i++];
+    return mw(req, user, dispatch);
+  };
+  return dispatch();
+}
+
+function clientKey(req: Request): string {
+  const ip =
+    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+    req.headers.get("x-real-ip") ||
+    "local";
+  return `${ip}:${new URL(req.url).pathname}`;
+}
+
+/** In-memory rate limit (dev / single process) */
+function memoryRateLimit(limit: number, windowMs: number): Middleware {
+  const hits = new Map<string, { count: number; reset: number }>();
+  return (req, _user, next) => {
+    const key = clientKey(req);
+    const now = Date.now();
+    let entry = hits.get(key);
+    if (!entry || now > entry.reset) {
+      entry = { count: 0, reset: now + windowMs };
+      hits.set(key, entry);
+    }
+    entry.count++;
+    if (entry.count > limit) {
+      return Response.json(
+        { error: "Too many requests" },
+        {
+          status: 429,
+          headers: { "Retry-After": String(Math.ceil((entry.reset - now) / 1000)) },
+        }
+      );
+    }
+    return next();
+  };
+}
+
+/** Redis atomic INCR rate limit — multi-instance safe */
+function redisRateLimit(limit: number, windowMs: number): Middleware {
+  return async (req, _user, next) => {
+    try {
+      const { cache } = await import("../../cache/src/index.js");
+      const key = `rl:${clientKey(req)}`;
+      const windowSec = Math.max(1, Math.ceil(windowMs / 1000));
+      const current = await cache.incr(key, windowSec);
+      if (current > limit) {
+        return Response.json(
+          { error: "Too many requests" },
+          { status: 429, headers: { "Retry-After": String(windowSec) } }
+        );
+      }
+      return next();
+    } catch {
+      return memoryRateLimit(limit, windowMs)(req, _user, next);
+    }
+  };
+}
+
+/**
+ * Rate limit: N requests per windowMs per IP+path.
+ * Uses Redis when RATE_LIMIT_DRIVER=redis or CACHE_DRIVER=redis.
+ */
+export function rateLimit(limit = 60, windowMs = 60_000): Middleware {
+  const driver = (config("RATE_LIMIT_DRIVER") || config("CACHE_DRIVER") || "memory").toLowerCase();
+  if (driver === "redis") return redisRateLimit(limit, windowMs);
+  return memoryRateLimit(limit, windowMs);
+}
+
+const authHits = new Map<string, { count: number; reset: number }>();
+
+/** Returns 429 when an auth POST endpoint is over limit, else null. */
+export function checkAuthRateLimit(req: Request): Response | null {
+  const limit = Number(config("AUTH_RATE_LIMIT") || 10);
+  if (limit <= 0) return null;
+  const path = new URL(req.url).pathname;
+  if (!path.startsWith("/api/auth/") || req.method !== "POST") return null;
+
+  const key = clientKey(req);
+  const now = Date.now();
+  let entry = authHits.get(key);
+  if (!entry || now > entry.reset) {
+    entry = { count: 0, reset: now + 60_000 };
+    authHits.set(key, entry);
+  }
+  entry.count++;
+  if (entry.count > limit) {
+    return Response.json(
+      { error: "Too many requests" },
+      {
+        status: 429,
+        headers: { "Retry-After": String(Math.ceil((entry.reset - now) / 1000)) },
+      }
+    );
+  }
+  return null;
+}
+
+export function cors(origins = "*"): Middleware {
+  return async (req, _user, next) => {
+    const res = await next();
+    const headers = new Headers(res.headers);
+    headers.set("Access-Control-Allow-Origin", origins);
+    headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
+    headers.set("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS");
+    if (req.method === "OPTIONS") {
+      return new Response(null, { status: 204, headers });
+    }
+    return new Response(res.body, { status: res.status, headers });
+  };
+}

package/packages/server/src/query.ts

@@ -0,0 +1,40 @@
+import type { ResourceDefinition } from "../../core/src/resource.js";
+import { fieldColumn } from "../../core/src/fields.js";
+import type { QueryOpts } from "../../database/src/query.js";
+
+const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+export function parseListQuery(url: URL, resource: ResourceDefinition): QueryOpts {
+  const page = Math.max(1, Number(url.searchParams.get("page") ?? 1));
+  const limit = Math.min(100, Math.max(1, Number(url.searchParams.get("limit") ?? 20)));
+  const offset = (page - 1) * limit;
+  const search = url.searchParams.get("search") ?? undefined;
+  const order = url.searchParams.get("order") === "asc" ? "asc" : "desc";
+
+  const allowedCols = new Set<string>(["id", "created_at", "updated_at"]);
+  if (resource.softDelete) allowedCols.add("deleted_at");
+
+  const filters: Record<string, string> = {};
+  for (const [name, field] of Object.entries(resource.fields)) {
+    const col = fieldColumn(name, field);
+    if (!col || !IDENT_RE.test(col)) continue;
+    allowedCols.add(col);
+    const val = url.searchParams.get(name) ?? url.searchParams.get(col);
+    if (val) filters[col] = val;
+  }
+
+  let sort = url.searchParams.get("sort") ?? undefined;
+  if (sort && (!IDENT_RE.test(sort) || !allowedCols.has(sort))) {
+    sort = undefined;
+  }
+
+  let softDelete: QueryOpts["softDelete"];
+  if (resource.softDelete) {
+    const trashed = url.searchParams.get("trashed");
+    if (trashed === "only") softDelete = "only";
+    else if (trashed === "with") softDelete = "with";
+    else softDelete = "exclude";
+  }
+
+  return { limit, offset, search, sort, order, filters, softDelete };
+}