@njinlabs/njin 0.7.0 → 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.0",
+  "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) {
@@ -197,14 +261,28 @@ export const makeModel = <Rules extends z.ZodObject>(
     // id/createdAt/updatedAt are always present on every record but aren't part of the
     // user-defined schema shape (they're injected in create()/update()) — allow sorting by them too.
     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.
-    const orderBy =
-      sort && sortableFields.has(sort)
-        ? `ORDER BY ${sort} ${order === "desc" ? "DESC" : "ASC"}`
-        : search && config.searchFields.length
-          ? `ORDER BY (${config.searchFields.map((_, i) => `search::score(${i + 1})`).join(" + ")}) DESC`
-          : "";
+    // (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 && searchPlan.some((e) => e.kind === "flat"));
+    const orderBy = hasExplicitSort
+      ? `ORDER BY ${sort} ${order === "desc" ? "DESC" : "ASC"}`
+      : useRelevance
+        ? "ORDER BY __relevance DESC"
+        : "";
+    const relevanceSelect = useRelevance
+      ? `, (${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
     const fetchFields =
@@ -216,16 +294,22 @@ export const makeModel = <Rules extends z.ZodObject>(
     const fetch = fetchFields.length ? `FETCH ${fetchFields.join(", ")}` : "";
     const start = (page - 1) * pageLimit;
 
-    const [data, [countRow]] = await surreal().query<[Returning[], { count: number }[]]>(
-      `SELECT * FROM ${prefix} ${where} ${orderBy} LIMIT ${pageLimit} START ${start} ${fetch};
+    const [rows, [countRow]] = await surreal().query<[(Returning & { __relevance?: number })[], { count: number }[]]>(
+      `SELECT *${relevanceSelect} FROM ${prefix} ${where} ${orderBy} LIMIT ${pageLimit} START ${start} ${fetch};
        SELECT count() as count FROM ${prefix} ${where} GROUP ALL`,
       params,
     );
 
+    const data = (rows ?? []).map((row) => {
+      if (!useRelevance) return row;
+      const { __relevance, ...rest } = row;
+      return rest as Returning;
+    });
+
     const total = countRow?.count ?? 0;
 
     return {
-      data: data ?? [],
+      data,
       meta: {
         total,
         page,

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,16 +1,20 @@
 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://"];
 
 export const isRemotePath = (path: string) => REMOTE_SCHEMES.some((scheme) => path.startsWith(scheme));
 
-// Shared by every model's search index (see ../core/model/index.ts's read()) — a `class`
-// tokenizer splits on Unicode character-class boundaries (language-agnostic word
-// splitting), and the `ngram` filter indexes overlapping 2-10 char slices of each token so
+// Shared by every model's search index (see ../core/model/index.ts's read()) — `blank`
+// tokenizer splits on whitespace only (unlike `class`, which also splits on punctuation:
+// "Next.js" would become "next" / "." / "js", and a lone "." can't form any 2-char ngram,
+// so a query for "next.js" — tokenized the same way — would never match). The `ngram`
+// filter then indexes overlapping 2-10 char slices of each whitespace-delimited token so
 // the `@N@` match operator can find a term anywhere inside a field (not just a whole-field
 // match) and still tolerate minor typos, similar to trigram search.
 const SEARCH_ANALYZER = "njin_search";
@@ -22,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();
@@ -36,18 +40,38 @@ const ensureTables = async (db: Surreal) => {
     await db.query(`DEFINE TABLE IF NOT EXISTS ${prefix} SCHEMALESS;`);
   }
 
-  await db.query(`DEFINE ANALYZER IF NOT EXISTS ${SEARCH_ANALYZER} TOKENIZERS class FILTERS lowercase,ngram(2,10);`);
+  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
-  for (const model of models) {
-    for (const field of model.searchFields ?? []) {
-      const key = `${model.prefix}.${field}`;
-      if (definedIndexes.has(key)) continue;
-      definedIndexes.add(key);
+  const defineSearchIndex = async (targetPrefix: string, field: string) => {
+    const key = `${targetPrefix}.${field}`;
+    if (definedIndexes.has(key)) return;
+    definedIndexes.add(key);
 
-      await db.query(
-        `DEFINE INDEX IF NOT EXISTS idx_search_${model.prefix}_${field} ON TABLE ${model.prefix} FIELDS ${field} SEARCH ANALYZER ${SEARCH_ANALYZER} BM25 HIGHLIGHTS;`,
-      );
+    // 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) {
+    // 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);
+      }
     }
   }
 };