@njinlabs/njin 0.2.0 → 0.3.0

package/README.md

@@ -131,6 +131,37 @@ This automatically generates:
 <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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njinlabs/njin",
-  "version": "0.2.0",
+  "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"],

package/src/core/config.ts

@@ -2,6 +2,7 @@ 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";
@@ -28,6 +29,11 @@ export type RouteFactory = () => Promise<{ default: AnyElysia }>;
 // 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?: {
@@ -50,6 +56,7 @@ export type NjinConfig = {
   events?: EventFactory[];
   routes?: RouteFactory[];
   vars?: VarsFactory[];
+  helpers?: HelperFactory[];
   plugins?: Plugin[];
 };
 
@@ -64,6 +71,7 @@ export type ResolvedConfig = {
   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.
@@ -131,6 +139,7 @@ export const loadConfig = async (preloaded?: NjinConfig): Promise<void> => {
     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/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 });

package/src/core/model/index.ts

@@ -272,6 +272,7 @@ export const makeModel = <Rules extends z.ZodObject>(
 export * from "./data_type";
 export * from "./hooks";
 export * from "../event";
+export * from "../helper";
 export * from "../plugin";
 export * from "../route";
 export * from "../vars";

package/src/core/plugin.ts

@@ -1,8 +1,9 @@
-import type { EventFactory, HookFactory, ModelFactory, RouteFactory, VarsFactory } from "./config";
+import type { EventFactory, HelperFactory, HookFactory, ModelFactory, RouteFactory, VarsFactory } from "./config";
 
 export type Plugin = {
   models?: ModelFactory[];
   vars?: VarsFactory[];
+  helpers?: HelperFactory[];
   hooks?: HookFactory[];
   events?: EventFactory[];
   routes?: RouteFactory[];

package/src/modules/view.ts

@@ -102,6 +102,11 @@ const view = makeModule(() => {
       edge.global(group.prefix, group);
     }
 
+    for (const helperPromise of getConfig().helpers) {
+      const { default: helper } = await helperPromise();
+      edge.global(helper.name, helper.fn);
+    }
+
     const controller = new Elysia();
 
     if (!isDev) {