@njinlabs/njin 0.2.0 → 0.4.0

package/README.md

@@ -1,5 +1,10 @@
 # njin
 
+[![CI](https://github.com/njinlabs/njin/actions/workflows/ci.yml/badge.svg)](https://github.com/njinlabs/njin/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/njinlabs/njin/actions/workflows/codeql.yml/badge.svg)](https://github.com/njinlabs/njin/actions/workflows/codeql.yml)
+[![npm version](https://img.shields.io/npm/v/%40njinlabs%2Fnjin.svg)](https://www.npmjs.com/package/@njinlabs/njin)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 A modern framework for building company profiles, landing pages, and content-driven websites. Define your data model once — get a full REST API, admin panel schema, and server-rendered website out of the box.
 
 ## Stack
@@ -13,7 +18,7 @@ A modern framework for building company profiles, landing pages, and content-dri
 ## Quick start
 
 ```bash
-bun create njin-app my-web
+bunx @njinlabs/njin create my-web
 cd my-web
 bunx njin dev
 ```
@@ -131,6 +136,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.
@@ -358,6 +394,7 @@ adapters: {
 ## Commands
 
 ```bash
+bunx @njinlabs/njin create my-web  # Scaffold a new project
 bunx njin dev       # Start dev server (Elysia + Vite HMR)
 bunx njin build     # Build for production -> ./out (public/, _admin/, views/, compiled server)
 bunx njin start     # Run from source in production mode (no compile)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njinlabs/njin",
-  "version": "0.2.0",
+  "version": "0.4.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/cli/create.ts

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const c = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", cyan: "\x1b[36m", green: "\x1b[32m" };
+
+const targetArg = process.argv[3] ?? ".";
+const targetDir = resolve(process.cwd(), targetArg);
+const projectName = targetArg === "." ? "njin-app" : targetArg.split(/[\\/]/).filter(Boolean).pop()!;
+
+if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+  console.error(`✖ Directory "${targetArg}" already exists and is not empty.`);
+  process.exit(1);
+}
+
+// This CLI's own package.json — read at runtime (not a static JSON import) so it
+// resolves correctly whether njin is a project-local dependency or fetched fresh
+// by `bunx`. Doubles as the source of truth for which tagged template to fetch,
+// and for the version pin written into the scaffolded project below.
+const pkg = await Bun.file(join(import.meta.dir, "../../package.json")).json();
+const tag = `v${pkg.version}`;
+const tarballUrl = `https://codeload.github.com/njinlabs/njin/tar.gz/refs/tags/${tag}`;
+
+console.log(`\nFetching template for njin ${tag}...\n`);
+
+const res = await fetch(tarballUrl);
+if (!res.ok || !res.body) {
+  console.error(
+    `✖ Could not download the project template for njin ${tag} (HTTP ${res.status}).\n` +
+      `  Check your internet connection, or that tag "${tag}" exists at github.com/njinlabs/njin.`,
+  );
+  process.exit(1);
+}
+
+mkdirSync(targetDir, { recursive: true });
+
+// `--strip-components=2` drops the `njin-<version>/template/` prefix baked into
+// GitHub's tag-tarball layout, so template/ contents land directly in targetDir.
+const tar = Bun.spawn(["tar", "-xz", "--strip-components=2", "-C", targetDir, `njin-${pkg.version}/template`], {
+  stdin: res.body,
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+const tarExitCode = await tar.exited;
+
+if (tarExitCode !== 0) {
+  console.error(
+    `✖ Failed to extract the template (tar exited with code ${tarExitCode}).\n` +
+      `  Make sure "tar" is installed and available on your PATH.`,
+  );
+  process.exit(tarExitCode);
+}
+
+const pkgPath = join(targetDir, "package.json");
+const scaffoldedPkg = await Bun.file(pkgPath).json();
+scaffoldedPkg.name = projectName;
+scaffoldedPkg.dependencies = { "@njinlabs/njin": `^${pkg.version}`, ...scaffoldedPkg.dependencies };
+await Bun.write(pkgPath, JSON.stringify(scaffoldedPkg, null, 2) + "\n");
+
+console.log("Installing dependencies...\n");
+
+const install = Bun.spawn(["bun", "install"], {
+  cwd: targetDir,
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+const installExitCode = await install.exited;
+
+if (installExitCode !== 0) {
+  console.error(`\n✖ "bun install" failed (exit code ${installExitCode}).`);
+  console.error(`  The project was scaffolded at ${targetDir}, but dependencies are not installed.`);
+  console.error(`  Run "cd ${targetArg} && bun install" manually to retry.\n`);
+  process.exit(installExitCode);
+}
+
+console.log(`
+  ${c.bold}${c.cyan}njin create${c.reset} ${c.dim}done${c.reset}
+
+  ${c.green}➜${c.reset}  cd ${targetArg === "." ? "." : targetArg}
+  ${c.green}➜${c.reset}  bunx njin dev
+`);

package/src/cli/index.ts

@@ -2,6 +2,9 @@
 const [command] = process.argv.slice(2);
 
 switch (command) {
+  case "create":
+    await import("./create");
+    break;
   case "dev":
     await import("./dev");
     break;
@@ -12,10 +15,11 @@ switch (command) {
     await import("./build");
     break;
   default:
-    console.log(`Usage: njin <dev|build|start>
+    console.log(`Usage: njin <create|dev|build|start>
 
-  dev    Run the dev server (Vite HMR + live reload)
-  build  Build for production -> ./out (public/, _admin/, views/, server)
-  start  Run from source in production mode (no compile)`);
+  create <dir>  Scaffold a new project (defaults to current directory)
+  dev           Run the dev server (Vite HMR + live reload)
+  build         Build for production -> ./out (public/, _admin/, views/, server)
+  start         Run from source in production mode (no compile)`);
     process.exit(command ? 1 : 0);
 }

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) {