@bhooai/nexus-core 0.1.6 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "@bhooai/nexus-core",
-  "version": "0.1.6",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,3 +38,4 @@
     "vitest": "^2.1.1"
   }
 }
+

package/src/app/ErrorHandler.ts

@@ -0,0 +1,65 @@
+/**
+ * ErrorHandler — global exception handler with content-negotiated rendering.
+ *
+ * Subclass + override `report` and/or `render`. Default behavior:
+ *   - JSON for Accept: application/json or /api/* paths
+ *   - HTML error pages otherwise, looked up from errors/pages/<status>.html
+ */
+import type { RequestContext } from '../http/context.js';
+import { NexusError, toNexusError } from '../errors.js';
+
+export type ErrorPageLookup = (status: number) => Promise<string | null>;
+
+export abstract class ErrorHandler {
+  /** log/submit the error (default: console). */
+  report(err: NexusError): void {
+    console.error(`[${err.code}]`, err.message, err.details ?? '');
+  }
+
+  /** Build a custom response body (any return type is serialized). */
+  toApiError(err: NexusError): unknown {
+    return {
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(err.details ? { details: err.details } : {}),
+      },
+    };
+  }
+
+  /** HTML page lookup. */
+  protected async pageFor(lookup: ErrorPageLookup, status: number): Promise<string | null> {
+    return lookup(status);
+  }
+
+  /** Render a styled error page; subclass can override. */
+  protected renderPage(pageHtml: string, _err: NexusError, _ctx: RequestContext): string {
+    return pageHtml;
+  }
+
+  /** Main entry — invoked by the framework when an error escapes handlers. */
+  async render(err: unknown, ctx: RequestContext, lookup: ErrorPageLookup): Promise<void> {
+    const ne = toNexusError(err);
+    this.report(ne);
+
+    const accept = (ctx.headers.accept as string) ?? '';
+    const wantsJson = accept.includes('application/json') || ctx.path.startsWith('/api') || ctx.path.startsWith('/admin');
+
+    if (wantsJson) {
+      ctx.json(this.toApiError(ne), ne.statusCode);
+      return;
+    }
+
+    const html = await this.pageFor(lookup, ne.statusCode);
+    if (html) {
+      ctx.html(this.renderPage(html, ne, ctx), ne.statusCode);
+      return;
+    }
+
+    // Fallback: plain-text error.
+    ctx.text(`${ne.statusCode} ${ne.code}: ${ne.message}`, ne.statusCode);
+  }
+}
+
+/** Default framework-provided handler. Subclass + override hooks. */
+export class DefaultErrorHandler extends ErrorHandler {}

package/src/app/FormRequest.ts

@@ -0,0 +1,43 @@
+/**
+ * FormRequest — Laravel-style validation + authorization wrapper for routes.
+ *
+ * Subclass + define `schema` (zod) + optional `authorize(ctx)`. Routes
+ * reference the class via `request: CreateUserRequest` in RouteDef; the
+ * framework parses the body and exposes validated data on `ctx.validated`.
+ *
+ * Manual usage:
+ *   const data = await CreateUserRequest.parse(ctx);
+ */
+import type { ZodTypeAny, infer as ZInfer } from 'zod';
+import type { RequestContext } from '../http/context.js';
+import { NexusError } from '../errors.js';
+
+export abstract class FormRequest<TSchema extends ZodTypeAny = ZodTypeAny> {
+  /** Zod schema applied to ctx.body. */
+  abstract readonly schema: TSchema;
+
+  /** Override to gate the request by authorization. Return false to 403. */
+  authorize(_ctx: RequestContext): boolean | Promise<boolean> {
+    return true;
+  }
+
+  /** Parse + validate ctx.body against `schema`. Throws 422 on failure. */
+  async validate(ctx: RequestContext): Promise<ZInfer<TSchema>> {
+    const allowed = await this.authorize(ctx);
+    if (!allowed) throw new NexusError('Request not authorized', { code: 'FORBIDDEN', statusCode: 403 });
+    const result = this.schema.safeParse(ctx.body);
+    if (!result.success) {
+      throw new NexusError('Validation failed', { code: 'VALIDATION', statusCode: 422, details: { issues: result.error.issues } });
+    }
+    return result.data as ZInfer<TSchema>;
+  }
+}
+
+/** Convenience for routes: parse + validate + return data in one call. */
+export async function validateBody<TSchema extends ZodTypeAny>(
+  RequestClass: new () => FormRequest<TSchema>,
+  ctx: RequestContext,
+): Promise<ZInfer<TSchema>> {
+  const req = new RequestClass();
+  return req.validate(ctx);
+}

package/src/app/Job.ts

@@ -0,0 +1,98 @@
+/**
+ * Job + queue abstraction. In-process by default; swap for Redis-backed
+ * adapter in production via configureQueue().
+ *
+ * Usage:
+ *   class SendWelcomeJob extends Job {
+ *     queue = 'mail';
+ *     async handle(user: User) { await WelcomeMail.to(user.email).send(); }
+ *   }
+ *   await SendWelcomeJob.dispatch(user);
+ */
+
+export interface JobPayload {
+  id: string;
+  queue: string;
+  runAt: number;
+  attempts: number;
+  args: unknown[];
+}
+
+export interface JobQueueAdapter {
+  enqueue(payload: JobPayload): Promise<void>;
+  dequeue(queue: string): Promise<JobPayload | null>;
+  /** Mark the job permanently failed. */
+  fail(payload: JobPayload, err: unknown): Promise<void>;
+  /** Requeue for retry with backoff. */
+  retry(payload: JobPayload, err: unknown): Promise<void>;
+}
+
+let activeAdapter: JobQueueAdapter | null = null;
+
+/** Configure the queue adapter; called by createNexusApp(). */
+export function configureQueue(adapter: JobQueueAdapter): void {
+  activeAdapter = adapter;
+}
+
+/** Backoff strategy: linear | exponential | fixed. */
+export type BackoffStrategy = 'linear' | 'exponential' | 'fixed';
+
+export abstract class Job<TArgs extends unknown[] = unknown[]> {
+  /** Queue name (default 'default'). */
+  queue: string = 'default';
+  /** Max retry attempts before marking failed. */
+  retries: number = 3;
+  /** Backoff strategy on retry. */
+  backoff: BackoffStrategy = 'exponential';
+
+  /** Handle the job. Throwing triggers retry/failure per `retries`. */
+  abstract handle(...args: TArgs): Promise<void>;
+
+  /** Enqueue this job. */
+  static async dispatch<T extends Job>(this: new (...args: never[]) => T, ...args: unknown[]): Promise<void> {
+    if (!activeAdapter) throw new Error('Queue adapter not configured — call configureQueue() during boot');
+    const instance = new this();
+    const payload: JobPayload = {
+      id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+      queue: instance.queue,
+      runAt: Date.now(),
+      attempts: 0,
+      args: args,
+    };
+    await activeAdapter.enqueue(payload);
+  }
+}
+
+/** Simple in-memory queue adapter — usable for dev and tests, NOT production. */
+export class InMemoryQueueAdapter implements JobQueueAdapter {
+  private queues = new Map<string, JobPayload[]>();
+  private dead: JobPayload[] = [];
+
+  async enqueue(payload: JobPayload): Promise<void> {
+    if (!this.queues.has(payload.queue)) this.queues.set(payload.queue, []);
+    this.queues.get(payload.queue)!.push(payload);
+  }
+
+  async dequeue(queue: string): Promise<JobPayload | null> {
+    const list = this.queues.get(queue);
+    if (!list || list.length === 0) return null;
+    const due = list.findIndex((p) => p.runAt <= Date.now());
+    if (due === -1) return null;
+    const [payload] = list.splice(due, 1);
+    return payload ?? null;
+  }
+
+  async fail(payload: JobPayload): Promise<void> {
+    this.dead.push(payload);
+  }
+
+  async retry(payload: JobPayload): Promise<void> {
+    const next: JobPayload = { ...payload, attempts: payload.attempts + 1, runAt: Date.now() + 1000 * (payload.attempts + 1) };
+    await this.enqueue(next);
+  }
+
+  /** Peek dead letters. */
+  deadLetter(): JobPayload[] {
+    return [...this.dead];
+  }
+}

package/src/app/Mailable.ts

@@ -0,0 +1,114 @@
+/**
+ * Mailable — declarative email class. Template lives in
+ * `mail/templates/<name>.ejs`; mailable class lives in
+ * `mail/mailables/<name>Mail.ts`.
+ *
+ *   class WelcomeMail extends Mailable {
+ *     subject = 'Welcome';
+ *     template = 'welcome';
+ *     constructor(public user: User) { super(); }
+ *     data() { return { name: this.user.name }; }
+ *   }
+ *
+ *   await WelcomeMail.to('a@b.com').send();
+ *   await WelcomeMail.to('a@b.com').queue();
+ */
+
+export interface MailContext {
+  to: string;
+  subject: string;
+  template: string;
+  data: Record<string, unknown>;
+}
+
+export interface MailDriver {
+  /** Send synchronously. Returns a provider id on success. */
+  send(payload: MailContext & { html: string; text?: string }): Promise<{ id: string }>;
+}
+
+let activeDriver: MailDriver | null = null;
+let templateRenderer: ((name: string, data: Record<string, unknown>) => Promise<{ html: string; text?: string }>) | null = null;
+let queueDispatcher: ((payload: { mailable: string; to: string; data: Record<string, unknown> }) => Promise<void>) | null = null;
+const registry = new Map<string, new (...args: never[]) => Mailable>();
+
+/** Configure the active mail driver. Called during boot. */
+export function configureMailDriver(driver: MailDriver): void {
+  activeDriver = driver;
+}
+
+/** Configure the template renderer. Called during boot by createNexusApp(). */
+export function configureMailRenderer(
+  renderer: (name: string, data: Record<string, unknown>) => Promise<{ html: string; text?: string }>,
+): void {
+  templateRenderer = renderer;
+}
+
+/** Wire mailable-queue dispatch (used by `.queue()`). */
+export function configureMailQueue(
+  dispatch: (payload: { mailable: string; to: string; data: Record<string, unknown> }) => Promise<void>,
+): void {
+  queueDispatcher = dispatch;
+}
+
+/** Register a Mailable class under its `template` name (for queue deserialization). */
+export function registerMailable(name: string, ctor: new (...args: never[]) => Mailable): void {
+  registry.set(name, ctor);
+}
+
+export abstract class Mailable {
+  /** Subject line. Override in subclass. */
+  abstract subject: string;
+  /** Template name (no extension) — file lives at mail/templates/<name>.ejs. */
+  abstract template: string;
+
+  protected toAddress: string | null = null;
+
+  /** Static entry point. */
+  static to<T extends Mailable>(this: new (...args: never[]) => T, address: string, ...args: unknown[]): T {
+    const ctor = this as unknown as new (...args: unknown[]) => T;
+    const inst = new ctor(...args);
+    inst.toAddress = address;
+    return inst;
+  }
+
+  /** Subclass hook: data passed to template. */
+  data(): Record<string, unknown> {
+    return {};
+  }
+
+  /** Send immediately via the active driver. */
+  async send(): Promise<{ id: string }> {
+    if (!activeDriver) throw new Error('Mail driver not configured');
+    if (!templateRenderer) throw new Error('Mail renderer not configured');
+    if (!this.toAddress) throw new Error('Mailable missing to-address — use Mailable.to(...)');
+    const rendered = await templateRenderer(this.template, this.data());
+    const name = (this as { constructor: { name: string } }).constructor.name;
+    registerMailable(name, this.constructor as new (...args: never[]) => Mailable);
+    return activeDriver.send({
+      to: this.toAddress,
+      subject: this.subject,
+      template: this.template,
+      data: this.data(),
+      html: rendered.html,
+      ...(rendered.text ? { text: rendered.text } : {}),
+    });
+  }
+
+  /** Enqueue via the configured queue dispatcher. */
+  async queue(): Promise<void> {
+    if (!queueDispatcher) throw new Error('Mail queue not configured');
+    if (!this.toAddress) throw new Error('Mailable missing to-address — use Mailable.to(...)');
+    const name = (this as { constructor: { name: string } }).constructor.name;
+    registerMailable(name, this.constructor as new (...args: never[]) => Mailable);
+    await queueDispatcher({ mailable: name, to: this.toAddress, data: this.data() });
+  }
+}
+
+/** Console logging driver (dev). */
+export const logMailDriver: MailDriver = {
+  async send(payload) {
+    console.log(`[mail] → ${payload.to} :: ${payload.subject}`);
+    if (process.env.NEXUS_MAIL_VERBOSE) console.log(payload.html);
+    return { id: `log-${Date.now()}` };
+  },
+};

package/src/app/Resource.ts

@@ -0,0 +1,37 @@
+/**
+ * Resource — API response transformer. Wraps a domain object as a
+ * versioned JSON-friendly shape, with helpers for single + collection.
+ */
+
+export abstract class Resource<T = unknown> {
+  constructor(protected value: T) {}
+
+  /** Convert underlying value → JSON-friendly object. Override in subclass. */
+  abstract toJSON(value: T, ctx?: unknown): unknown;
+
+  /** Include a field conditionally. */
+  protected when<TVal>(condition: boolean, v: TVal): TVal | undefined {
+    return condition ? v : undefined;
+  }
+
+  /** Include a field only when present. */
+  protected whenPresent<TVal>(v: TVal | null | undefined): TVal | undefined {
+    return v === null || v === undefined ? undefined : v;
+  }
+
+  /** Build the JSON payload. */
+  serialize(ctx?: unknown): unknown {
+    return this.toJSON(this.value, ctx);
+  }
+
+  /** Static convenience: serialize a single value. */
+  static make<T, R extends Resource<T>>(this: new (v: T) => R, value: T, ctx?: unknown): unknown {
+    const r = new this(value);
+    return r.serialize(ctx);
+  }
+
+  /** Static convenience: serialize a collection. */
+  static collection<T, R extends Resource<T>>(this: new (v: T) => R, values: T[], ctx?: unknown): unknown[] {
+    return values.map((v) => new this(v).serialize(ctx));
+  }
+}

package/src/app/Seeder.ts

@@ -0,0 +1,17 @@
+/**
+ * Seeder — database seeding. Auto-discovered from database/seeds/.
+ *
+ * Run via `nexus db:seed` (CLI) or programmatically:
+ *   const seeds = await loadSeeders('database/seeds');
+ *   for (const S of seeds) await new S().run();
+ */
+
+export abstract class Seeder {
+  /** Seed name (defaults to class name). */
+  get name(): string {
+    return (this as { constructor: { name: string } }).constructor.name;
+  }
+
+  /** Override — perform the seeding. */
+  abstract run(): Promise<void>;
+}

package/src/app/ServiceProvider.ts

@@ -0,0 +1,16 @@
+/**
+ * ServiceProvider — Laravel-style registration + boot for DI.
+ *
+ * register(container)  — wire singletons into the container
+ * boot(container)      — async init after all providers registered
+ *
+ * Discovered automatically from `providers/*.ts` by `createNexusApp()`.
+ */
+import type { Container } from '../di/Container.js';
+
+export abstract class ServiceProvider {
+  /** Wire singletons. */
+  register(_container: Container): void {}
+  /** Post-registration init. */
+  async boot(_container: Container): Promise<void> {}
+}