@njinlabs/njin 0.7.1 → 0.8.0

package/README.md

@@ -63,6 +63,11 @@ const post = makeModel("post", {
 export default post;
 ```
 
+`searchFields` can also reach one level into a `relation`/`multiRelation`/`file`/`multiFile` field
+using dot notation, e.g. `searchFields: ["title", "author.name"]` to search `post` by its related
+`author`'s `name` field. A bad reference (the local field isn't a relation, or more than one level
+of nesting is used) throws when `makeModel()` is called, not at query time.
+
 Register it in `config.ts` at the project root:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njinlabs/njin",
-  "version": "0.7.1",
+  "version": "0.8.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/model/index.ts

@@ -63,6 +63,56 @@ const OPERATORS: Record<FilterOperator, (field: string, param: string) => string
   $in:         (f, p) => `${f} CONTAINS $${p}`,
 };
 
+const RELATION_RENDER_AS = ["relation", "multi_relation", "file", "multi_file"];
+
+// Every makeModel() call registers its own schema here before returning — since
+// relation()/relationMany() require the actual built target Model as an argument,
+// the target's makeModel() is guaranteed to have already run (and registered itself)
+// by the time a field referencing it via relation() can even be constructed. Used
+// only for the opportunistic target-field check in resolveSearchPlan below.
+const schemaRegistry = new Map<string, z.ZodObject>();
+
+export type ResolvedSearchField =
+  | { kind: "flat"; field: string }
+  | { kind: "nested"; local: string; targetPrefix: string; targetField: string; multi: boolean };
+
+// Parses searchFields entries into flat field names and single-hop nested
+// "relationField.targetField" references, validating relation-family fields and
+// (when the target model has already registered itself) the target field's existence
+// synchronously — so a bad reference throws at model-definition time, not per-request.
+export const resolveSearchPlan = (schema: z.ZodObject, searchFields: string[], modelName: string): ResolvedSearchField[] => {
+  return searchFields.map((raw): ResolvedSearchField => {
+    const dot = raw.indexOf(".");
+    if (dot === -1) return { kind: "flat", field: raw };
+
+    if (raw.indexOf(".", dot + 1) !== -1) {
+      throw new Error(`Model "${modelName}": searchFields entry "${raw}" has more than one level of nesting — only a single relation hop is supported.`);
+    }
+
+    const local = raw.slice(0, dot);
+    const targetField = raw.slice(dot + 1);
+    const meta = (schema.shape[local] as z.ZodType | undefined)?.meta() as any;
+
+    if (!meta || !RELATION_RENDER_AS.includes(meta.renderAs)) {
+      throw new Error(`Model "${modelName}": searchFields entry "${raw}" references "${local}", which is not a relation/file field on this model's schema.`);
+    }
+
+    const targetPrefix = meta.model as string;
+    const targetSchema = schemaRegistry.get(targetPrefix);
+    if (targetSchema && !(targetField in targetSchema.shape)) {
+      throw new Error(`Model "${modelName}": searchFields entry "${raw}" references field "${targetField}", which does not exist on model "${targetPrefix}".`);
+    }
+
+    return {
+      kind: "nested",
+      local,
+      targetPrefix,
+      targetField,
+      multi: meta.renderAs === "multi_relation" || meta.renderAs === "multi_file",
+    };
+  });
+};
+
 export const makeModel = <Rules extends z.ZodObject>(
   prefix: string,
   config: {
@@ -80,15 +130,19 @@ export const makeModel = <Rules extends z.ZodObject>(
 
   const table = new Table(prefix);
 
+  schemaRegistry.set(prefix, config.schema);
+
   const relationFields = Object.entries(config.schema.shape)
     .filter(([, v]) => {
       const m = (v as z.ZodType).meta() as any;
-      return ["relation", "multi_relation", "file", "multi_file"].includes(m?.renderAs);
+      return RELATION_RENDER_AS.includes(m?.renderAs);
     })
     .map(([k]) => k);
 
   const relationFieldSet = new Set(relationFields);
 
+  const searchPlan = resolveSearchPlan(config.schema, config.searchFields, config.name);
+
   const uniqueFields = Object.entries(config.schema.shape)
     .filter(([, v]) => (v as z.ZodType).meta()?.unique === true)
     .map(([k]) => k);
@@ -160,11 +214,21 @@ export const makeModel = <Rules extends z.ZodObject>(
     // below any usable threshold even though the term is clearly present. The @N@ match
     // operator + ngram analyzer gives real substring/partial-word matching, BM25 relevance
     // ranking, and still tolerates minor typos via shared n-grams.
-    if (search && config.searchFields.length) {
+    //
+    // A nested entry (searchPlan `kind: "nested"`, e.g. "author.name") becomes an IN/CONTAINSANY
+    // subquery against the target table instead — the local relation field holds a record link,
+    // not text, so it can't carry its own full-text index. All entries (flat and nested alike)
+    // share one running @N@ counter in declaration order, since SurrealDB's match-ref scoping
+    // across a WHERE-clause subquery on a different table isn't something to assume either way.
+    if (search && searchPlan.length) {
       params.search = search.trim();
-      whereParts.push(
-        `(${config.searchFields.map((f, i) => `${f} @${i + 1}@ $search`).join(" OR ")})`,
-      );
+      const clauses = searchPlan.map((entry, i) => {
+        const n = i + 1;
+        if (entry.kind === "flat") return `${entry.field} @${n}@ $search`;
+        const op = entry.multi ? "CONTAINSANY" : "IN";
+        return `${entry.local} ${op} (SELECT VALUE id FROM ${entry.targetPrefix} WHERE ${entry.targetField} @${n}@ $search)`;
+      });
+      whereParts.push(`(${clauses.join(" OR ")})`);
     }
 
     if (filters) {
@@ -199,18 +263,25 @@ export const makeModel = <Rules extends z.ZodObject>(
     const sortableFields = new Set([...Object.keys(config.schema.shape), "id", "createdAt", "updatedAt"]);
     const hasExplicitSort = Boolean(sort && sortableFields.has(sort));
     // An explicit sort always wins; otherwise, when searching, rank by BM25 relevance
-    // (summed across every matched search field) instead of leaving result order unspecified.
+    // (summed across every matched flat search field) instead of leaving result order
+    // unspecified. Nested (relation) entries are excluded from this sum — a match found via
+    // the IN/CONTAINSANY subquery above has no per-record score in this query's context, since
+    // it happened on a different table entirely. If a model's searchFields are all nested,
+    // there's no score to rank by, so relevance ordering is skipped (same as no searchFields).
     // `ORDER BY` only accepts a bare identifier here, not a function call — so relevance is
     // projected as an aliased field below (SELECT ... AS __relevance) and stripped back out
     // of each returned record afterwards, since it isn't part of the model's schema.
-    const useRelevance = !hasExplicitSort && Boolean(search && config.searchFields.length);
+    const useRelevance = !hasExplicitSort && Boolean(search && searchPlan.some((e) => e.kind === "flat"));
     const orderBy = hasExplicitSort
       ? `ORDER BY ${sort} ${order === "desc" ? "DESC" : "ASC"}`
       : useRelevance
         ? "ORDER BY __relevance DESC"
         : "";
     const relevanceSelect = useRelevance
-      ? `, (${config.searchFields.map((_, i) => `search::score(${i + 1})`).join(" + ")}) AS __relevance`
+      ? `, (${searchPlan
+          .map((e, i) => (e.kind === "flat" ? `search::score(${i + 1})` : null))
+          .filter((s): s is string => s !== null)
+          .join(" + ")}) AS __relevance`
       : "";
 
     // Validate populate against known relation fields — prevents FETCH injection

package/src/modules/file.ts

@@ -3,7 +3,7 @@ import type { makeModel } from "../core/model";
 import { makeModule } from "../core/module";
 import { resolveSafePath } from "../core/path_guard";
 import Elysia from "elysia";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { RecordId } from "surrealdb";
 import z from "zod";
 import auth from "./auth";

package/src/modules/surreal.ts

@@ -1,7 +1,9 @@
 import { getConfig } from "../core/config";
+import { resolveSearchPlan } from "../core/model";
 import { makeModule } from "../core/module";
 import { Surreal, createRemoteEngines } from "surrealdb";
 import type { Engines } from "surrealdb";
+import type { z } from "zod";
 
 const REMOTE_SCHEMES = ["ws://", "wss://", "http://", "https://"];
 const EMBEDDED_SCHEMES = ["mem://", "rocksdb://", "surrealkv://"];
@@ -24,7 +26,7 @@ const ensureTables = async (db: Surreal) => {
   const { default: userModel } = await import("../models/user");
   const { default: fileModel } = await import("../models/file");
 
-  const models: { prefix: string; searchFields?: string[] }[] = [userModel, fileModel];
+  const models: { prefix: string; searchFields?: string[]; validation?: z.ZodObject }[] = [userModel, fileModel];
 
   for (const factory of getConfig().models) {
     const { default: model } = await factory();
@@ -40,18 +42,36 @@ const ensureTables = async (db: Surreal) => {
 
   await db.query(`DEFINE ANALYZER IF NOT EXISTS ${SEARCH_ANALYZER} TOKENIZERS blank FILTERS lowercase,ngram(2,10);`);
 
-  const definedIndexes = new Set<string>(); // dedupe prefix+field in case two factories share a prefix
+  const defineSearchIndex = async (targetPrefix: string, field: string) => {
+    const key = `${targetPrefix}.${field}`;
+    if (definedIndexes.has(key)) return;
+    definedIndexes.add(key);
+
+    // FULLTEXT, not SEARCH — this SurrealDB version renamed the index-type keyword;
+    // SEARCH ANALYZER ... is a parse error here even though older docs/examples use it.
+    await db.query(
+      `DEFINE INDEX IF NOT EXISTS idx_search_${targetPrefix}_${field} ON TABLE ${targetPrefix} FIELDS ${field} FULLTEXT ANALYZER ${SEARCH_ANALYZER} BM25 HIGHLIGHTS;`,
+    );
+  };
+
+  const definedIndexes = new Set<string>(); // dedupe prefix+field in case two factories share a prefix, or a nested reference targets an already-indexed field
   for (const model of models) {
-    for (const field of model.searchFields ?? []) {
-      const key = `${model.prefix}.${field}`;
-      if (definedIndexes.has(key)) continue;
-      definedIndexes.add(key);
-
-      // FULLTEXT, not SEARCH — this SurrealDB version renamed the index-type keyword;
-      // SEARCH ANALYZER ... is a parse error here even though older docs/examples use it.
-      await db.query(
-        `DEFINE INDEX IF NOT EXISTS idx_search_${model.prefix}_${field} ON TABLE ${model.prefix} FIELDS ${field} FULLTEXT ANALYZER ${SEARCH_ANALYZER} BM25 HIGHLIGHTS;`,
-      );
+    // A nested searchFields entry (e.g. "author.name") needs its index defined on the
+    // *target* table/field instead — the local relation field holds a record link, not
+    // text. model.validation carries the schema needed to resolve that; if it's missing for
+    // some reason, fall back to treating every entry as flat (today's behavior) rather than
+    // throwing here — an authoring bug in a dotted entry is makeModel()'s job to catch, not
+    // table setup's.
+    const plan = model.validation
+      ? resolveSearchPlan(model.validation, model.searchFields ?? [], model.prefix)
+      : (model.searchFields ?? []).map((field) => ({ kind: "flat" as const, field }));
+
+    for (const entry of plan) {
+      if (entry.kind === "flat") {
+        await defineSearchIndex(model.prefix, entry.field);
+      } else {
+        await defineSearchIndex(entry.targetPrefix, entry.targetField);
+      }
     }
   }
 };