@njinlabs/njin 0.1.2 → 0.2.0

package/src/core/model/hooks.ts

@@ -0,0 +1,143 @@
+export type HookEvent =
+  | "beforeCreate"
+  | "afterCreate"
+  | "beforeUpdate"
+  | "afterUpdate"
+  | "beforeDestroy"
+  | "afterDestroy"
+  | "beforeVarsUpdate"
+  | "afterVarsUpdate";
+
+// Minimal structural shape needed from a model instance to infer hook types —
+// deliberately not importing makeModel's return type here to avoid a circular
+// import with ./index.ts (which imports this file).
+type AnyModel = {
+  prefix: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  create: (...args: any[]) => Promise<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  update: (...args: any[]) => Promise<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  destroy: (...args: any[]) => Promise<any>;
+};
+
+type RecordOf<M extends AnyModel> = Awaited<ReturnType<M["create"]>>;
+type CreateDataOf<M extends AnyModel> = Parameters<M["create"]>[0];
+type UpdateDataOf<M extends AnyModel> = Parameters<M["update"]>[1];
+
+// Minimal structural shape needed from a vars group (makeVars, ../vars/index.ts) —
+// singleton settings object, no create/destroy, and update(data) takes a single
+// argument (no id, unlike a model's update(id, data): there's only ever one record
+// per vars group, keyed by its own prefix).
+type AnyVars = {
+  prefix: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  update: (...args: any[]) => Promise<any>;
+};
+
+type VarsRecordOf<V extends AnyVars> = Awaited<ReturnType<V["update"]>>;
+type VarsUpdateDataOf<V extends AnyVars> = Parameters<V["update"]>[0];
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type HookHandler = (...args: any[]) => unknown;
+
+const registry = new Map<string, Map<HookEvent, HookHandler[]>>();
+
+const register = (event: HookEvent, prefix: string, fn: HookHandler) => {
+  let byEvent = registry.get(prefix);
+  if (!byEvent) {
+    byEvent = new Map();
+    registry.set(prefix, byEvent);
+  }
+
+  const handlers = byEvent.get(event);
+  if (handlers) {
+    handlers.push(fn);
+  } else {
+    byEvent.set(event, [fn]);
+  }
+};
+
+export const beforeCreate = <M extends AnyModel>(
+  model: M,
+  fn: (
+    data: Partial<CreateDataOf<M>>,
+  ) => void | Partial<CreateDataOf<M>> | Promise<void | Partial<CreateDataOf<M>>>,
+): void => register("beforeCreate", model.prefix, fn);
+
+export const afterCreate = <M extends AnyModel>(model: M, fn: (record: RecordOf<M>) => void | Promise<void>): void =>
+  register("afterCreate", model.prefix, fn);
+
+export const beforeUpdate = <M extends AnyModel>(
+  model: M,
+  fn: (
+    data: Partial<UpdateDataOf<M>>,
+    context: { id: string },
+  ) => void | Partial<UpdateDataOf<M>> | Promise<void | Partial<UpdateDataOf<M>>>,
+): void => register("beforeUpdate", model.prefix, fn);
+
+export const afterUpdate = <M extends AnyModel>(model: M, fn: (record: RecordOf<M>) => void | Promise<void>): void =>
+  register("afterUpdate", model.prefix, fn);
+
+export const beforeDestroy = <M extends AnyModel>(model: M, fn: (id: string) => void | Promise<void>): void =>
+  register("beforeDestroy", model.prefix, fn);
+
+export const afterDestroy = <M extends AnyModel>(model: M, fn: (record: RecordOf<M>) => void | Promise<void>): void =>
+  register("afterDestroy", model.prefix, fn);
+
+export const beforeVarsUpdate = <V extends AnyVars>(
+  vars: V,
+  fn: (
+    data: Partial<VarsUpdateDataOf<V>>,
+  ) => void | Partial<VarsUpdateDataOf<V>> | Promise<void | Partial<VarsUpdateDataOf<V>>>,
+): void => register("beforeVarsUpdate", vars.prefix, fn);
+
+export const afterVarsUpdate = <V extends AnyVars>(
+  vars: V,
+  fn: (record: VarsRecordOf<V>) => void | Promise<void>,
+): void => register("afterVarsUpdate", vars.prefix, fn);
+
+// Internal dispatch used by makeModel — runs handlers sequentially (await each),
+// merges before*-handler return values into data, and lets errors propagate so a
+// throwing hook aborts the operation (same contract as UniqueConstraintError).
+export const runBeforeHooks = async <T extends Record<string, unknown>>(
+  event: "beforeCreate" | "beforeUpdate" | "beforeVarsUpdate",
+  prefix: string,
+  data: Partial<T>,
+  context: { id?: string },
+): Promise<Partial<T>> => {
+  const handlers = registry.get(prefix)?.get(event) as
+    | ((data: Partial<T>, context: { id?: string }) => void | Partial<T> | Promise<void | Partial<T>>)[]
+    | undefined;
+  if (!handlers?.length) return data;
+
+  let current = data;
+  for (const handler of handlers) {
+    const result = await handler(current, context);
+    if (result) current = { ...current, ...result };
+  }
+
+  return current;
+};
+
+export const runAfterHooks = async <T>(
+  event: "afterCreate" | "afterUpdate" | "afterDestroy" | "afterVarsUpdate",
+  prefix: string,
+  record: T,
+): Promise<void> => {
+  const handlers = registry.get(prefix)?.get(event) as ((record: T) => void | Promise<void>)[] | undefined;
+  if (!handlers?.length) return;
+
+  for (const handler of handlers) {
+    await handler(record);
+  }
+};
+
+export const runBeforeDestroyHooks = async (prefix: string, id: string): Promise<void> => {
+  const handlers = registry.get(prefix)?.get("beforeDestroy") as ((id: string) => void | Promise<void>)[] | undefined;
+  if (!handlers?.length) return;
+
+  for (const handler of handlers) {
+    await handler(id);
+  }
+};

package/src/core/model/index.ts

@@ -2,6 +2,7 @@ import surreal from "../../modules/surreal";
 import moment from "moment";
 import { RecordId, Table, type Values } from "surrealdb";
 import { z } from "zod";
+import { runAfterHooks, runBeforeDestroyHooks, runBeforeHooks } from "./hooks";
 
 export type FormMeta = {
   label: string;
@@ -93,6 +94,13 @@ export const makeModel = <Rules extends z.ZodObject>(
 
   const uniqueFieldSet = new Set(uniqueFields);
 
+  // A real Set, not `key in config.schema.shape` — `in` also matches inherited
+  // Object.prototype members (e.g. "constructor", "toString"), and JSON.parse can
+  // produce those as literal own-properties on a request body/query object, letting
+  // them slip past a schema-shape membership check and get interpolated as a field
+  // name into the raw query string built below.
+  const filterableFieldSet = new Set(Object.keys(config.schema.shape));
+
   // field must be a known unique field — prevents arbitrary field injection
   const isDuplicate = async (field: string, value: unknown, excludeId?: string) => {
     if (!uniqueFieldSet.has(field)) return false;
@@ -118,13 +126,19 @@ export const makeModel = <Rules extends z.ZodObject>(
   };
 
   const create = async (data: Values<Data>) => {
-    await assertUnique(data);
+    const merged = (await runBeforeHooks("beforeCreate", prefix, data as Record<string, unknown>, {})) as Values<Data>;
+
+    await assertUnique(merged);
 
-    return surreal()
+    const record = (await surreal()
       .create<Data>(table)
-      .content({ ...data, createdAt: moment().toISOString(), updatedAt: moment().toISOString() })
+      .content({ ...merged, createdAt: moment().toISOString(), updatedAt: moment().toISOString() })
       .output("after")
-      .then(([data]) => data) as Promise<Returning>;
+      .then(([data]) => data)) as Returning;
+
+    await runAfterHooks("afterCreate", prefix, record);
+
+    return record;
   };
 
   const read = async ({
@@ -149,7 +163,7 @@ export const makeModel = <Rules extends z.ZodObject>(
     if (filters) {
       for (const [key, value] of Object.entries(filters)) {
         // key must exist in schema — prevents arbitrary field injection
-        if (!(key in config.schema.shape)) continue;
+        if (!filterableFieldSet.has(key)) continue;
 
         if (typeof value === "string") {
           // Shorthand: filters[field]=value → equality
@@ -214,18 +228,32 @@ export const makeModel = <Rules extends z.ZodObject>(
   };
 
   const update = async (id: string, data: Values<Partial<Data>>) => {
-    await assertUnique(data, id);
+    const merged = (await runBeforeHooks("beforeUpdate", prefix, data as Record<string, unknown>, {
+      id,
+    })) as Values<Partial<Data>>;
+
+    await assertUnique(merged, id);
 
-    return surreal()
+    const record = (await (surreal()
       .update<Data>(new RecordId(table, id))
       .merge({
-        ...data,
+        ...merged,
         updatedAt: moment().toISOString(),
-      }) as unknown as Promise<Returning>;
+      }) as unknown as Promise<Returning>)) as Returning;
+
+    await runAfterHooks("afterUpdate", prefix, record);
+
+    return record;
   };
 
-  const destroy = (id: string) => {
-    return surreal().delete<Data>(new RecordId(table, id)) as unknown as Promise<Returning>;
+  const destroy = async (id: string) => {
+    await runBeforeDestroyHooks(prefix, id);
+
+    const record = (await (surreal().delete<Data>(new RecordId(table, id)) as unknown as Promise<Returning>)) as Returning;
+
+    await runAfterHooks("afterDestroy", prefix, record);
+
+    return record;
   };
 
   return {
@@ -242,3 +270,8 @@ export const makeModel = <Rules extends z.ZodObject>(
 };
 
 export * from "./data_type";
+export * from "./hooks";
+export * from "../event";
+export * from "../plugin";
+export * from "../route";
+export * from "../vars";

package/src/core/path_guard.ts

@@ -1,9 +1,23 @@
-import { join, normalize } from "node:path";
+import { basename, join, normalize, sep } from "node:path";
 
 // Resolves `requestedPath` against `baseDir` and rejects anything that escapes it
 // (e.g. "../../etc/passwd") — shared by every module that serves files straight
 // off disk based on a request path (uploads, admin panel SPA, etc).
 export const resolveSafePath = (baseDir: string, requestedPath: string): string | null => {
+  // A bare `startsWith` prefix check would let "/app/uploads-evil" pass for a
+  // baseDir of "/app/uploads" — anchor the comparison to a directory boundary
+  // instead so only baseDir itself (or a path inside it) matches.
+  const normalizedBase = normalize(baseDir);
+  const boundary = normalizedBase.endsWith(sep) ? normalizedBase : normalizedBase + sep;
   const resolved = normalize(join(baseDir, requestedPath));
-  return resolved.startsWith(baseDir) ? resolved : null;
+  return resolved === normalizedBase || resolved.startsWith(boundary) ? resolved : null;
+};
+
+// Strips any directory component from a client-supplied filename (e.g. a multipart
+// upload's `file.name`), leaving only the final path segment. Without this, a name
+// like "../../../config.ts" would let an upload adapter write (or an S3 key target)
+// outside the directory/prefix it's meant to be confined to.
+export const sanitizeFileName = (name: string): string => {
+  const base = basename(name);
+  return base === "" || base === "." || base === ".." ? "file" : base;
 };

package/src/core/plugin.ts

@@ -0,0 +1,13 @@
+import type { EventFactory, HookFactory, ModelFactory, RouteFactory, VarsFactory } from "./config";
+
+export type Plugin = {
+  models?: ModelFactory[];
+  vars?: VarsFactory[];
+  hooks?: HookFactory[];
+  events?: EventFactory[];
+  routes?: RouteFactory[];
+  init?: () => Promise<void> | void;
+};
+
+// Identity function — DX/typing only, same purpose as defineConfig/route().
+export const definePlugin = (plugin: Plugin): Plugin => plugin;

package/src/core/route.ts

@@ -0,0 +1,6 @@
+import { Elysia } from "elysia";
+
+// Thin factory over Elysia itself — purely for DX (autocomplete/type-checking),
+// same purpose as defineConfig. Custom route files get the full Elysia API
+// (schema validation, guards, groups, macros, ...) with no wrapping layer.
+export const route = (config?: ConstructorParameters<typeof Elysia>[0]) => new Elysia(config);

package/src/core/vars/index.ts

@@ -0,0 +1,64 @@
+import surreal from "../../modules/surreal";
+import moment from "moment";
+import { RecordId, Table, type Values } from "surrealdb";
+import { z } from "zod";
+import { runAfterHooks, runBeforeHooks } from "../model/hooks";
+
+// One shared physical table for every VARS group — rows are keyed by each
+// group's own prefix as the record id (vars:general, vars:seo, ...), not one
+// table per group. See surreal.ts's ensureTables() for the DEFINE TABLE call.
+const table = new Table("vars");
+
+export const makeVars = <Rules extends z.ZodObject>(
+  prefix: string,
+  config: {
+    schema: Rules;
+    name: string;
+  },
+) => {
+  type Data = z.infer<Rules>;
+  type Returning = Data & { updatedAt: string | null };
+
+  const recordId = new RecordId(table, prefix);
+
+  // schema.parse() fills in every field's .default() for anything missing —
+  // including the row never having been saved at all — so get() always
+  // returns a complete, valid object. Every VARS field is expected to
+  // declare a .default(...) for this reason.
+  const get = async (): Promise<Returning> => {
+    const record = await surreal().select<Data & { updatedAt?: string }>(recordId);
+    const { updatedAt, ...rest } = (record ?? {}) as Record<string, unknown> & { updatedAt?: string };
+    return { ...(config.schema.parse(rest) as Data), updatedAt: updatedAt ?? null };
+  };
+
+  // Upsert, not update — the row may not exist yet on first save.
+  const update = async (data: Values<Partial<Data>>): Promise<Returning> => {
+    const merged = (await runBeforeHooks(
+      "beforeVarsUpdate",
+      prefix,
+      data as Record<string, unknown>,
+      {},
+    )) as Values<Partial<Data>>;
+
+    const record = (await surreal()
+      .upsert<Data & { updatedAt: string }>(recordId)
+      .merge({ ...merged, updatedAt: moment().toISOString() } as Values<Data & { updatedAt: string }>)
+      .output("after")) as (Data & { updatedAt: string }) | undefined;
+
+    const { updatedAt, ...rest } = (record ?? {}) as Record<string, unknown> & { updatedAt?: string };
+    const result = { ...(config.schema.parse(rest) as Data), updatedAt: updatedAt ?? null };
+
+    await runAfterHooks("afterVarsUpdate", prefix, result);
+
+    return result;
+  };
+
+  return {
+    name: config.name,
+    prefix,
+    table,
+    validation: config.schema,
+    get,
+    update,
+  };
+};

package/src/modules/api.ts

@@ -5,13 +5,49 @@ import z from "zod";
 import auth from "./auth";
 import elysia from "./elysia";
 
+// Shared by both models and vars groups on the /api/schema endpoint — strips
+// non-JSON-representable renderAs types (relation/multi_relation/file) into
+// plain JSON-schema shapes the admin panel can render a form from.
+const toAdminSchema = (schema: z.ZodObject) =>
+  schema.toJSONSchema({
+    unrepresentable: "any",
+    override: (ctx) => {
+      if (ctx.jsonSchema.renderAs === "relation") {
+        ctx.jsonSchema.type = "object";
+        ctx.jsonSchema.properties = {
+          id: {
+            type: "string",
+          },
+        };
+        ctx.jsonSchema.required = ["id"];
+        ctx.jsonSchema.additionalProperties = {};
+      } else if (ctx.jsonSchema.renderAs === "multi_relation") {
+        (ctx.jsonSchema.items! as any).type = "string";
+      } else if (ctx.jsonSchema.renderAs === "file") {
+        ctx.jsonSchema.type = "string";
+      }
+    },
+  });
+
 const api = makeModule(() => {
   const fn = () => {};
 
   fn.init = async () => {
     const models = getConfig().models;
+    const hooks = getConfig().hooks;
+    const events = getConfig().events;
+    const routes = getConfig().routes;
+    const varsGroups = getConfig().vars;
     const authPlugin = await auth();
 
+    // Trigger each hook file's import side effect (afterCreate()/etc. registration)
+    // before any route goes live, so hooks are always registered before the first request.
+    for (const promise of hooks) await promise();
+
+    // Same reasoning as hooks above, for the event bus (src/core/event.ts): drain
+    // every listener file's .listen() registration before any route goes live.
+    for (const promise of events) await promise();
+
     const controller = new Elysia({ prefix: "/api/schema" }).use(authPlugin.plugin).get(
       "/",
       async () => {
@@ -23,31 +59,27 @@ const api = makeModule(() => {
               return {
                 name: data.name,
                 prefix: data.prefix,
-                schema: data.validation.toJSONSchema({
-                  unrepresentable: "any",
-                  override: (ctx) => {
-                    if (ctx.jsonSchema.renderAs === "relation") {
-                      ctx.jsonSchema.type = "object";
-                      ctx.jsonSchema.properties = {
-                        id: {
-                          type: "string",
-                        },
-                      };
-                      ctx.jsonSchema.required = ["id"];
-                      ctx.jsonSchema.additionalProperties = {};
-                    } else if (ctx.jsonSchema.renderAs === "multi_relation") {
-                      (ctx.jsonSchema.items! as any).type = "string";
-                    } else if (ctx.jsonSchema.renderAs === "file") {
-                      ctx.jsonSchema.type = "string";
-                    }
-                  },
-                }),
+                schema: toAdminSchema(data.validation),
+              };
+            })(),
+          ),
+        );
+
+        const allVars = await Promise.all(
+          varsGroups.map((varsGroup) =>
+            (async () => {
+              const { default: group } = await varsGroup();
+
+              return {
+                name: group.name,
+                prefix: group.prefix,
+                schema: toAdminSchema(group.validation),
               };
             })(),
           ),
         );
 
-        return { data: allModels };
+        return { data: allModels, vars: allVars };
       },
       {
         auth: true,
@@ -151,6 +183,11 @@ const api = makeModule(() => {
       elysia().use(controller);
     }
 
+    for (const promise of routes) {
+      const { default: plugin } = await promise();
+      elysia().use(plugin);
+    }
+
     return {};
   };