@njinlabs/njin 0.1.2 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ A modern framework for building company profiles, landing pages, and content-dri
 
 - **[Bun](https://bun.sh)** — runtime, package manager, bundler (njin is Bun-only — no Node/Deno support)
 - **[Elysia](https://elysiajs.com)** — HTTP framework with type-safe CRUD generation
-- **[SurrealDB](https://surrealdb.com)** — embedded multi-model database (no separate server)
+- **[SurrealDB](https://surrealdb.com)** — multi-model database, embedded by default (no separate server) or pointed at a remote instance
 - **[EdgeJS](https://edgejs.dev)** — server-side template engine with file-based routing
 - **[Vite](https://vitejs.dev)** + **[Tailwind CSS v4](https://tailwindcss.com)** + **[Alpine.js](https://alpinejs.dev)** — frontend tooling
 
@@ -82,6 +82,170 @@ This automatically generates:
 | `DELETE` | `/api/post/:id` | Delete |
 | `GET` | `/api/schema` | Full schema for admin panel |
 
+## Vars — user-editable settings
+
+`vars` groups are singleton settings objects (site name, SEO meta, feature toggles, ...) meant to be edited later through an admin panel — unlike a model, there's no list of records, just one object per group.
+
+```ts
+// src/vars/general.ts
+import { makeVars, text, boolean } from "@njinlabs/njin";
+import z from "zod";
+
+const general = makeVars("general", {
+  name: "General",
+  schema: z.object({
+    // Every field needs a .default(...) — there's no "create" step, so
+    // get() must always return a complete object even before anything
+    // has ever been saved.
+    siteName: text({ label: "Site Name" }, (z) => z.default("My Site")),
+    maintenanceMode: boolean({ label: "Maintenance Mode" }, (z) => z.default(false)),
+  }),
+});
+
+export default general;
+```
+
+Register it in `config.ts`:
+
+```ts
+// config.ts
+export default defineConfig({
+  vars: [
+    () => import("./src/vars/general"),
+  ],
+});
+```
+
+This automatically generates:
+
+| Method | Endpoint | Description |
+|--------|----------|--------------|
+| `GET` | `/api/vars/general` | Read current values (defaults-filled even before the first save) |
+| `PUT` | `/api/vars/general` | Partial update — merges into the existing values |
+| `GET` | `/api/schema` | Also lists every registered vars group's schema, under a `vars` key |
+
+`vars` groups are also available in templates as global async functions, same as models — but only `get()`/`update()`, not the full model method set:
+
+```edge
+@let(settings = await general.get())
+<title>{{ settings.siteName }}</title>
+```
+
+## Helpers — custom template functions
+
+`helpers` register a plain, stateless function as an Edge global — unlike `vars`/`models`, there's no DB record and no auto-generated REST endpoint, just a function callable from any `.edge` template.
+
+```ts
+// src/helpers/format_date.ts
+import { defineHelper } from "@njinlabs/njin";
+import moment from "moment";
+
+export default defineHelper("formatDate", (date: string, format = "DD MMM YYYY") =>
+  moment(date).format(format),
+);
+```
+
+Register it in `config.ts`:
+
+```ts
+// config.ts
+export default defineConfig({
+  helpers: [
+    () => import("./src/helpers/format_date"),
+  ],
+});
+```
+
+Use it directly in a template, no `await` needed since it's a plain synchronous function (an `async` `fn` works too, called with `await` like any other async global):
+
+```edge
+<p>{{ formatDate(post.createdAt) }}</p>
+```
+
+## Events
+
+A type-safe event bus for fan-out notifications (e.g. "an order was paid", "a user registered") — different from model hooks (`beforeCreate`/`afterCreate`/...): hooks are scoped to one model and can abort the operation by throwing, while events are fire-and-forget — a listener that throws is logged but never stops other listeners or the code that dispatched.
+
+`makeEvent()` has no name — dispatch and listen are correlated by sharing the same instance (not a string key), so always define one event in one canonical file and import it wherever you need it:
+
+```ts
+// src/events/order_paid.ts
+import { makeEvent } from "@njinlabs/njin";
+
+const orderPaid = makeEvent<{ orderId: string; total: number }>();
+
+export default orderPaid;
+```
+
+```ts
+// src/events/listeners/send_receipt.ts
+import orderPaid from "../order_paid";
+
+orderPaid.listen(async (payload) => {
+  // errors here are caught and logged, they never bubble back to whoever dispatched
+  console.log(`Sending receipt for order ${payload.orderId} ($${payload.total})`);
+});
+```
+
+Register the listener file in `config.ts` so it's imported (and its `.listen()` call runs) at boot:
+
+```ts
+// config.ts
+export default defineConfig({
+  events: [
+    () => import("./src/events/listeners/send_receipt"),
+  ],
+});
+```
+
+## Plugins
+
+A plugin bundles models/vars/hooks/events/routes into one reusable, installable unit — like a self-contained njin app that extends whatever project installs it. It's a factory function that takes options and returns its bundle, so it ships as a plain npm package:
+
+```ts
+// my-plugin/index.ts
+import { definePlugin } from "@njinlabs/njin";
+
+export default (options: { apiKey: string }) =>
+  definePlugin({
+    models: [() => import("./models/order")],
+    routes: [() => import("./routes/webhook")],
+    init: async () => {
+      // runs once at boot, before any model/route/hook/event goes live —
+      // validate options, construct an SDK client, etc.
+    },
+  });
+```
+
+Register it in `config.ts` — the factory is called directly (not wrapped in another thunk), same as `adapters.file`:
+
+```ts
+// config.ts
+import myPlugin from "my-plugin";
+
+export default defineConfig({
+  plugins: [myPlugin({ apiKey: process.env.MY_PLUGIN_KEY! })],
+});
+```
+
+Everything a plugin contributes is merged in ahead of your own project's models/vars/hooks/events/routes — so your project's own registrations always run after, and can build on top of what the plugin sets up.
+
+Dispatch from anywhere — for example, composing with a model's `afterCreate` hook:
+
+```ts
+// src/models/order.ts
+import { makeModel, afterCreate } from "@njinlabs/njin";
+import orderPaid from "../events/order_paid";
+
+const order = makeModel("order", { /* ... */ });
+
+afterCreate(order, (record) => {
+  orderPaid.dispatch({ orderId: record.id.id, total: record.total });
+});
+
+export default order;
+```
+
 ## File-based routing
 
 Files in `src/views/pages/` map to routes automatically:
@@ -179,6 +343,12 @@ export default defineConfig({
     path: process.env.DB_PATH ?? "rocksdb://data",
     namespace: process.env.DB_NAMESPACE ?? "general",
     database: process.env.DB_DATABASE ?? "general",
+    // only needed for a remote db.path — username/password (root/system auth) or a token
+    auth: process.env.DB_TOKEN
+      ? process.env.DB_TOKEN
+      : process.env.DB_USERNAME && process.env.DB_PASSWORD
+        ? { username: process.env.DB_USERNAME, password: process.env.DB_PASSWORD }
+        : undefined,
   },
   img: {
     hosts: ["cdn.example.com"], // external hosts allowed for GET /img besides same-origin/localhost
@@ -189,9 +359,17 @@ export default defineConfig({
   models: [
     () => import("./src/models/post"),
   ],
+  vars: [
+    () => import("./src/vars/general"),
+  ],
+  events: [
+    () => import("./src/events/listeners/send_receipt"),
+  ],
 });
 ```
 
+`db.path` accepts either an embedded scheme — `rocksdb://<dir>` (default), `mem://` (in-memory, wiped on restart), `surrealkv://<dir>` — or a remote one — `ws://`, `wss://`, `http://`, `https://` — pointed at a running `surreal start` instance or SurrealDB Cloud. `db.auth` is only needed for a remote instance that requires it, and accepts either `{ username, password }` (root/system auth) or a bearer token string. Switching between embedded and remote is just a config/env change for `njin dev`/`njin start`; a compiled `njin build` binary bakes in whichever mode was resolved at build time (see below).
+
 To store uploads in S3 (or an S3-compatible service like R2/Spaces/MinIO) instead:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njinlabs/njin",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "A modern framework for building company profiles, landing pages, and content-driven websites.",
   "type": "module",
   "keywords": ["bun", "elysia", "surrealdb", "edgejs", "cms", "framework"],
@@ -18,7 +18,8 @@
   },
   "files": ["src", "LICENSE"],
   "scripts": {
-    "test": "bun test"
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage"
   },
   "bin": {
     "njin": "./src/cli/index.ts"

package/src/cli/build.ts

@@ -39,16 +39,36 @@ if (existsSync(adminDir)) {
   console.log("• No _admin found — skipped");
 }
 
-// surreal.ts statically imports @surrealdb/node unconditionally, and module.ts always wires
-// up the surreal module, so every compiled binary needs this native binding to boot — even
-// for projects using a remote SurrealDB instance. Its loader resolves the platform .node file
-// via `const require = createRequire(import.meta.url); require("./surrealdb-node.<platform>.node")`
-// — using a local `require` value rather than the literal CJS keyword means Bun's bundler never
-// statically recognizes that call as an import to resolve/embed, so it survives bundling
-// untouched and then fails at runtime in a compiled binary (no real filesystem path next to
-// `import.meta.url` to load it from). So instead of embedding it, the matching platform binary
-// is copied next to the executable as a plain file, and a build plugin patches the loader's
-// source to read from there (via `process.execPath`'s directory) at runtime.
+// surreal.ts only imports @surrealdb/node dynamically, on the embedded-db.path branch — so a
+// project whose resolved db.path is remote (ws/wss/http/https) never needs its native binding
+// at all. We resolve the project's own config here (same file loadConfig() reads from
+// process.cwd() at runtime) to decide, at build time, whether to bundle it.
+const { loadConfig, getConfig } = await import("../core/config");
+const { isRemotePath } = await import("../modules/surreal");
+
+// If the project's config.ts can't be resolved here (missing, throws, or its db.path depends
+// on an env var not set at build time), default to embedded — the binding just goes unused in
+// a genuinely remote deployment, same as today, rather than risking a binary that can't do
+// embedded mode if the env var resolves differently at runtime than it did at build time.
+let isRemoteBuild = false;
+try {
+  await loadConfig();
+  isRemoteBuild = isRemotePath(getConfig().db.path);
+} catch {
+  isRemoteBuild = false;
+}
+
+// surreal.ts's dynamic import() of @surrealdb/node is still literal-specifier, so Bun's
+// bundler would otherwise trace and embed it regardless of which branch runs at runtime. Its
+// loader resolves the platform .node file via `const require = createRequire(import.meta.url);
+// require("./surrealdb-node.<platform>.node")` — using a local `require` value rather than the
+// literal CJS keyword means Bun's bundler never statically recognizes that call as an import to
+// resolve/embed, so when the package IS bundled it survives untouched and then fails at runtime
+// in a compiled binary (no real filesystem path next to `import.meta.url` to load it from). So
+// for an embedded build, instead of embedding it, the matching platform binary is copied next
+// to the executable as a plain file, and a build plugin patches the loader's source to read
+// from there (via `process.execPath`'s directory) at runtime. For a remote build, the package
+// is excluded from the bundle entirely (see `external` below) since that branch is unreachable.
 const NATIVE_FILE: Record<string, string> = {
   "win32-x64": "surrealdb-node.win32-x64-msvc.node",
   "win32-arm64": "surrealdb-node.win32-arm64-msvc.node",
@@ -58,34 +78,39 @@ const NATIVE_FILE: Record<string, string> = {
   "linux-x64": "surrealdb-node.linux-x64-gnu.node",
   "linux-arm64": "surrealdb-node.linux-arm64-gnu.node",
 };
-const nativeFile = NATIVE_FILE[`${process.platform}-${process.arch}`];
-if (!nativeFile) {
-  console.error(`\n✗ Unsupported platform for @surrealdb/node: ${process.platform}-${process.arch}`);
-  process.exit(1);
-}
 
-const surrealNodeDistDir = dirname(fileURLToPath(import.meta.resolve("@surrealdb/node")));
-const bindingsDir = join(outDir, "bindings");
-await mkdir(bindingsDir, { recursive: true });
-await cp(join(surrealNodeDistDir, nativeFile), join(bindingsDir, nativeFile));
-console.log(`✓ Copied native binding -> out/bindings/${nativeFile}`);
+let surrealNativePlugin: BunPlugin | undefined;
+if (isRemoteBuild) {
+  console.log("• Remote db.path detected — skipping @surrealdb/node native binding");
+} else {
+  const nativeFile = NATIVE_FILE[`${process.platform}-${process.arch}`];
+  if (!nativeFile) {
+    console.error(`\n✗ Unsupported platform for @surrealdb/node: ${process.platform}-${process.arch}`);
+    process.exit(1);
+  }
 
-const surrealNativePlugin: BunPlugin = {
-  name: "surrealdb-native-binding",
-  setup(build) {
-    build.onLoad({ filter: /surrealdb-node\.mjs$/ }, async (args) => {
-      const original = await Bun.file(args.path).text();
-      const marker = "const require = createRequire(import.meta.url);";
-      if (!original.includes(marker)) {
-        throw new Error("@surrealdb/node's loader shape changed — expected createRequire marker not found");
-      }
-      // Wrap `require` so the host platform's own .node lookup is redirected to the copy in
-      // out/bindings/; every other platform's file and the optional sibling npm packages fall
-      // through to the real require() and fail exactly as they would unpatched (still recorded
-      // in the loader's own loadErrors, so a genuinely missing binding still throws clearly).
-      const patched = original.replace(
-        marker,
-        `const __realRequire = createRequire(import.meta.url);
+  const surrealNodeDistDir = dirname(fileURLToPath(import.meta.resolve("@surrealdb/node")));
+  const bindingsDir = join(outDir, "bindings");
+  await mkdir(bindingsDir, { recursive: true });
+  await cp(join(surrealNodeDistDir, nativeFile), join(bindingsDir, nativeFile));
+  console.log(`✓ Copied native binding -> out/bindings/${nativeFile}`);
+
+  surrealNativePlugin = {
+    name: "surrealdb-native-binding",
+    setup(build) {
+      build.onLoad({ filter: /surrealdb-node\.mjs$/ }, async (args) => {
+        const original = await Bun.file(args.path).text();
+        const marker = "const require = createRequire(import.meta.url);";
+        if (!original.includes(marker)) {
+          throw new Error("@surrealdb/node's loader shape changed — expected createRequire marker not found");
+        }
+        // Wrap `require` so the host platform's own .node lookup is redirected to the copy in
+        // out/bindings/; every other platform's file and the optional sibling npm packages fall
+        // through to the real require() and fail exactly as they would unpatched (still recorded
+        // in the loader's own loadErrors, so a genuinely missing binding still throws clearly).
+        const patched = original.replace(
+          marker,
+          `const __realRequire = createRequire(import.meta.url);
 const require = (specifier) => {
   if (specifier === ${JSON.stringify(`./${nativeFile}`)}) {
     const path = __realRequire("node:path");
@@ -93,11 +118,12 @@ const require = (specifier) => {
   }
   return __realRequire(specifier);
 };`,
-      );
-      return { contents: patched, loader: "js" };
-    });
-  },
-};
+        );
+        return { contents: patched, loader: "js" };
+      });
+    },
+  };
+}
 
 // Generated build entry — a static, literal import of the project's config.ts so
 // `bun build --compile` can trace and embed it (and the model files it dynamically
@@ -114,11 +140,16 @@ const require = (specifier) => {
 // binary still points at node_modules/geoip-lite/data on the machine that ran `njin build` —
 // which won't exist wherever the binary is actually deployed. Same fix shape as the SurrealDB
 // native binding above: ship the data dir next to the executable and patch the lookup.
+// Only the country .dat files are shipped — analytics.ts only ever reads the `country` field,
+// and geoip-lite falls back to country-only mode automatically when the (much larger, ~100MB)
+// city .dat files are absent, keeping the buffers it preloads into memory at startup small.
 const geoipLibDir = dirname(fileURLToPath(import.meta.resolve("geoip-lite")));
 const geoipDataDir = join(geoipLibDir, "..", "data");
 const outGeoipDataDir = join(outDir, "geoip-data");
-await cp(geoipDataDir, outGeoipDataDir, { recursive: true });
-console.log("✓ Copied geoip-lite data -> out/geoip-data");
+await mkdir(outGeoipDataDir, { recursive: true });
+await cp(join(geoipDataDir, "geoip-country.dat"), join(outGeoipDataDir, "geoip-country.dat"));
+await cp(join(geoipDataDir, "geoip-country6.dat"), join(outGeoipDataDir, "geoip-country6.dat"));
+console.log("✓ Copied geoip-lite country data -> out/geoip-data");
 
 const geoipDataPlugin: BunPlugin = {
   name: "geoip-lite-data-dir",
@@ -166,9 +197,11 @@ printBanner({ mode: "production" });
     entrypoints: [entryPath],
     compile: { outfile: join(outDir, exeName) },
     // vite is dev-only (view.ts gates it behind `if (isDev)`, dead in production) — bundling
-    // it would also drag in its own internal (not-installed) lazy `import("esbuild")`.
-    external: ["vite"],
-    plugins: [surrealNativePlugin, geoipDataPlugin],
+    // it would also drag in its own internal (not-installed) lazy `import("esbuild")`. Same
+    // reasoning for @surrealdb/node on a remote build — surreal.ts's dynamic import of it is
+    // unreachable when db.path is remote, so it's safe to leave unresolved.
+    external: isRemoteBuild ? ["vite", "@surrealdb/node"] : ["vite"],
+    plugins: [surrealNativePlugin, geoipDataPlugin].filter((p): p is BunPlugin => p !== undefined),
     // The CLI's `bun build --compile` implicitly inlines process.env.NODE_ENV as "production";
     // the Bun.build() JS API doesn't, so view.ts's top-level `isDev` check would otherwise read
     // undefined and take the dev branch (importing the externalized, not-on-disk `vite`).
@@ -185,8 +218,11 @@ printBanner({ mode: "production" });
 
   console.log(`\n✓ Compiled server -> out/${exeName}`);
   console.log(
-    "\nNote: out/bindings/ and out/geoip-data/ must ship alongside the executable — they hold " +
-      "the native SurrealDB binding and the geoip-lite database loaded at runtime.",
+    isRemoteBuild
+      ? "\nNote: out/geoip-data/ must ship alongside the executable — it holds the geoip-lite " +
+          "database loaded at runtime. No native SurrealDB binding was bundled (remote db.path)."
+      : "\nNote: out/bindings/ and out/geoip-data/ must ship alongside the executable — they hold " +
+          "the native SurrealDB binding and the geoip-lite database loaded at runtime.",
   );
   console.log(`\nRun it with:\n  cd out && ./${exeName}`);
 } finally {

package/src/config/module.ts

@@ -7,9 +7,11 @@ import elysia from "../modules/elysia";
 import file from "../modules/file";
 import img from "../modules/img";
 import logger from "../modules/logger";
+import plugin from "../modules/plugin";
 import setup from "../modules/setup";
 import surreal from "../modules/surreal";
 import users from "../modules/users";
+import vars from "../modules/vars";
 import view from "../modules/view";
 
 // Must resolve before anything below reads getConfig() — db path, port, file
@@ -18,12 +20,20 @@ await loadConfig();
 
 const modules = [
   logger.init(),
-  surreal.init(),
+  // Awaited — surreal's init() now performs the actual DB connect (see surreal.ts),
+  // so plugin.init() below (which may query the DB, e.g. reading its own vars group)
+  // never runs against an unconnected instance.
+  await surreal.init(),
   elysia.init(),
+  // Early — after elysia/surreal singletons exist (and surreal is connected), but well
+  // before api.init() (which drains hooks/events and mounts models/routes) — so a
+  // plugin's own setup always finishes before its own contributed routes/hooks/events go live.
+  await plugin.init(),
   await file.init(),
   await auth.init(),
   await setup.init(),
   await api.init(),
+  await vars.init(),
   await img.init(),
   await analytics.init(),
   await users.init(),

package/src/core/adapters/bun_filesystem.ts

@@ -2,6 +2,7 @@ import type { FileAdapter } from "../../modules/file";
 import { init } from "@paralleldrive/cuid2";
 import { join } from "node:path";
 import z from "zod";
+import { sanitizeFileName } from "../path_guard";
 
 const createId = init({
   random: Math.random,
@@ -16,7 +17,7 @@ const bunFilesystemAdapter = ({ dir = "./uploads" }: { dir?: string } = {}): Fil
     meta,
     dir,
     write: async (file) => {
-      const [fileName, ...exts] = file.name.split(".");
+      const [fileName, ...exts] = sanitizeFileName(file.name).split(".");
 
       const name = `${fileName}_${createId()}.${exts.join(".")}`;
 

package/src/core/adapters/s3.ts

@@ -2,6 +2,7 @@ import type { FileAdapter } from "../../modules/file";
 import { init } from "@paralleldrive/cuid2";
 import type { S3Options } from "bun";
 import z from "zod";
+import { sanitizeFileName } from "../path_guard";
 
 const createId = init({
   random: Math.random,
@@ -40,7 +41,7 @@ const s3Adapter = (options: S3Options & { bucket: string; publicUrl?: string }):
   return {
     meta,
     write: async (file) => {
-      const [fileName, ...exts] = file.name.split(".");
+      const [fileName, ...exts] = sanitizeFileName(file.name).split(".");
       const key = `${fileName}_${createId()}.${exts.join(".")}`;
 
       await bucket.write(key, file, { acl: "public-read", type: file.type });

package/src/core/config.ts

@@ -1,16 +1,48 @@
+import type { AnyElysia } from "elysia";
 import type { FileAdapter } from "../modules/file";
 import { join } from "node:path";
 import bunFilesystemAdapter from "./adapters/bun_filesystem";
+import type { Helper } from "./helper";
 import type { makeModel } from "./model";
+import type { Plugin } from "./plugin";
+import type { makeVars } from "./vars";
 
 export type ModelFactory = () => Promise<{ default: ReturnType<typeof makeModel> }>;
 
+// A hook file's only job is the side effect of calling afterCreate()/etc. at import
+// time — its module's exports (if any) are irrelevant, unlike ModelFactory.
+export type HookFactory = () => Promise<unknown>;
+
+// An event listener file's only job is the side effect of calling `<event>.listen(...)`
+// at import time — it imports a canonical makeEvent() instance from its own file
+// (src/core/event.ts) and registers a handler. Same shape/reasoning as HookFactory.
+export type EventFactory = () => Promise<unknown>;
+
+// A route file exports a full Elysia instance (built via the `route()` helper) —
+// its default export is mounted as-is, same as ModelFactory but for arbitrary endpoints.
+// AnyElysia (not a bare `Elysia`) because each route file's instance carries its own
+// concrete generics (prefix literal, schemas, ...) that a fixed default-generic
+// `Elysia` type can't structurally match — same reasoning as elysia.ts's shared app.
+export type RouteFactory = () => Promise<{ default: AnyElysia }>;
+
+// A vars file's default export is one makeVars() group (e.g. "general", "seo") —
+// a singleton settings object, not a list of records like a model.
+export type VarsFactory = () => Promise<{ default: ReturnType<typeof makeVars> }>;
+
+// A helper file's default export is one defineHelper() — a stateless function
+// registered as an Edge global by its own name, unlike models/vars which are
+// DB-backed objects registered by prefix.
+export type HelperFactory = () => Promise<{ default: Helper }>;
+
 export type NjinConfig = {
   port?: number;
   db?: {
     path?: string;
     namespace?: string;
     database?: string;
+    // Root/system auth ({ username, password }) or a bearer token (string). Omit for an
+    // anonymous connection — the only mode embedded (rocksdb/mem/surrealkv) engines support.
+    auth?: { username: string; password: string } | string;
   };
   img?: {
     hosts?: string[];
@@ -20,15 +52,30 @@ export type NjinConfig = {
     file?: FileAdapter<any>;
   };
   models?: ModelFactory[];
+  hooks?: HookFactory[];
+  events?: EventFactory[];
+  routes?: RouteFactory[];
+  vars?: VarsFactory[];
+  helpers?: HelperFactory[];
+  plugins?: Plugin[];
 };
 
 export type ResolvedConfig = {
   port: number;
-  db: { path: string; namespace: string; database: string };
+  db: { path: string; namespace: string; database: string; auth?: { username: string; password: string } | string };
   img: { hosts: string[] };
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   adapters: { file: FileAdapter<any> };
   models: ModelFactory[];
+  hooks: HookFactory[];
+  events: EventFactory[];
+  routes: RouteFactory[];
+  vars: VarsFactory[];
+  helpers: HelperFactory[];
+  // Everything else a Plugin contributes (models/vars/hooks/events/routes) is already
+  // flattened into the arrays above — init() is the only part that can't be merged away,
+  // so it's the only piece of each Plugin that survives resolution on its own.
+  pluginInits: Array<() => Promise<void> | void>;
 };
 
 // Identity function — purely for DX (autocomplete/type-checking on the config
@@ -70,16 +117,30 @@ export const loadConfig = async (preloaded?: NjinConfig): Promise<void> => {
     }
   }
 
+  const plugins = userConfig.plugins ?? [];
+
+  // Plugin-contributed models/vars/hooks/events/routes come first, then the project's
+  // own — a plugin is the foundation being extended, so its registrations run first and
+  // the project's own can build on top of (or follow) whatever the plugin set up. No
+  // collision detection: two plugins (or a plugin and the project) registering the same
+  // prefix fails the same way it already does today — naturally, at runtime.
   resolved = {
     port: userConfig.port ?? 3000,
     db: {
       path: userConfig.db?.path ?? "rocksdb://data",
       namespace: userConfig.db?.namespace ?? "general",
       database: userConfig.db?.database ?? "general",
+      auth: userConfig.db?.auth,
     },
     img: { hosts: userConfig.img?.hosts ?? [] },
     adapters: { file: userConfig.adapters?.file ?? bunFilesystemAdapter() },
-    models: userConfig.models ?? [],
+    models: [...plugins.flatMap((p) => p.models ?? []), ...(userConfig.models ?? [])],
+    hooks: [...plugins.flatMap((p) => p.hooks ?? []), ...(userConfig.hooks ?? [])],
+    events: [...plugins.flatMap((p) => p.events ?? []), ...(userConfig.events ?? [])],
+    routes: [...plugins.flatMap((p) => p.routes ?? []), ...(userConfig.routes ?? [])],
+    vars: [...plugins.flatMap((p) => p.vars ?? []), ...(userConfig.vars ?? [])],
+    helpers: [...plugins.flatMap((p) => p.helpers ?? []), ...(userConfig.helpers ?? [])],
+    pluginInits: plugins.map((p) => p.init).filter((fn): fn is () => Promise<void> | void => typeof fn === "function"),
   };
 };
 

package/src/core/event.ts

@@ -0,0 +1,45 @@
+import logger from "../modules/logger";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Handler<T> = (payload: T) => void | Promise<void>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const registry = new Map<symbol, Handler<any>[]>();
+
+export interface EventBus<T = void> {
+  dispatch: (payload: T) => Promise<void>;
+  listen: (handler: Handler<T>) => void;
+}
+
+// Opens a new channel on the shared event bus — no name/string key: correlation
+// between dispatch() and listen() happens purely via sharing this same returned
+// instance (import it from one canonical file), not via a global string registry.
+// This is what makes T genuinely type-safe — dispatch and listen on one instance
+// always share the same T, there's no way for two unrelated call sites to silently
+// disagree on payload shape. The Symbol key routes through one shared `registry`
+// Map so the whole app still runs on a single underlying bus.
+export const makeEvent = <T = void>(): EventBus<T> => {
+  const key = Symbol();
+  registry.set(key, []);
+
+  const listen: EventBus<T>["listen"] = (handler) => {
+    registry.get(key)!.push(handler);
+  };
+
+  // Runs every listener sequentially (await each) — a throwing/rejecting listener
+  // is caught and logged, NOT propagated: this is a fan-out notification, not a
+  // validation/abort hook like hooks.ts, so one broken listener must never stop
+  // its siblings or bubble into the dispatch() caller.
+  const dispatch: EventBus<T>["dispatch"] = async (payload) => {
+    const handlers = registry.get(key) ?? [];
+    for (const handler of handlers) {
+      try {
+        await handler(payload);
+      } catch (err) {
+        logger().error(err, "Event listener threw");
+      }
+    }
+  };
+
+  return { dispatch, listen };
+};

package/src/core/helper.ts

@@ -0,0 +1,5 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Helper = { name: string; fn: (...args: any[]) => unknown };
+
+// Identity function — DX/typing only, same purpose as defineConfig/definePlugin.
+export const defineHelper = (name: string, fn: Helper["fn"]): Helper => ({ name, fn });