contentbase 0.0.1 → 0.0.4

package/src/query/collection-query.ts

@@ -2,7 +2,7 @@ import { QueryBuilder } from "./query-builder";
 import { operators } from "./operators";
 import { createModelInstance } from "../model-instance";
 import type { Collection } from "../collection";
-import type { ModelDefinition, InferModelInstance } from "../types";
+import type { ModelDefinition, InferModelInstance, SerializeOptions } from "../types";
 
 /**
  * CollectionQuery is a typed query builder for a specific model type.
@@ -12,14 +12,24 @@ import type { ModelDefinition, InferModelInstance } from "../types";
  *   const results = await collection
  *     .query(Epic)
  *     .where("meta.priority", "high")
+ *     .include("plans")
  *     .fetchAll();
  */
+interface SortSpec {
+  path: string;
+  direction: "asc" | "desc";
+}
+
 export class CollectionQuery<
   TDef extends ModelDefinition<any, any, any, any, any>,
 > {
   #collection: Collection;
   #definition: TDef;
   #queryBuilder: QueryBuilder;
+  #sorts: SortSpec[] = [];
+  #limit: number | undefined;
+  #offset: number | undefined;
+  #include: string[] = [];
 
   constructor(collection: Collection, definition: TDef) {
     this.#collection = collection;
@@ -27,6 +37,26 @@ export class CollectionQuery<
     this.#queryBuilder = new QueryBuilder();
   }
 
+  /**
+   * Include related models in query results.
+   * Named relationships will be eagerly resolved and included in toJSON() output.
+   *
+   * @example
+   *   await collection.query(Project).include("plans").fetchAll()
+   *   await collection.query(Project).include("plans", "goal").fetchAll()
+   */
+  include(...names: string[]): this {
+    this.#include.push(...names);
+    return this;
+  }
+
+  /** Returns the serialize options based on include() calls */
+  get serializeOptions(): SerializeOptions {
+    const opts: SerializeOptions = {};
+    if (this.#include.length > 0) opts.related = this.#include;
+    return opts;
+  }
+
   where(
     pathOrObject: string | Record<string, unknown>,
     operatorOrValue?: any,
@@ -96,22 +126,41 @@ export class CollectionQuery<
     return this;
   }
 
+  scope(name: string): this {
+    const scopeFn = (this.#definition as any).scopes?.[name];
+    if (!scopeFn) {
+      throw new Error(`Unknown scope "${name}" on model "${this.#definition.name}"`);
+    }
+    return scopeFn(this) as this;
+  }
+
+  sort(path: string, direction: "asc" | "desc" = "asc"): this {
+    this.#sorts.push({ path, direction });
+    return this;
+  }
+
+  limit(n: number): this {
+    this.#limit = n;
+    return this;
+  }
+
+  offset(n: number): this {
+    this.#offset = n;
+    return this;
+  }
+
   async fetchAll(): Promise<InferModelInstance<TDef>[]> {
     const collection = this.#collection;
     if (!collection.loaded) await collection.load();
 
     const definition = this.#definition;
     const conditions = this.#queryBuilder.conditions;
-    const results: InferModelInstance<TDef>[] = [];
+    let results: InferModelInstance<TDef>[] = [];
 
     for (const pathId of collection.available) {
-      // Filter by model type BEFORE creating instances (fixes original perf bug)
-      const item = collection.items.get(pathId)!;
-      const matchesModel = definition.match
-        ? definition.match({ id: pathId, meta: item.meta })
-        : pathId.startsWith(definition.prefix);
-
-      if (!matchesModel) continue;
+      // Delegate all matching logic to collection (handles _model meta, prefix, Base fallback)
+      const matchedDef = collection.findModelDefinition(pathId);
+      if (matchedDef?.name !== definition.name) continue;
 
       const doc = collection.document(pathId);
       const instance = createModelInstance(doc, definition, collection);
@@ -127,6 +176,44 @@ export class CollectionQuery<
       }
     }
 
+    if (this.#sorts.length > 0) {
+      results.sort((a, b) => {
+        for (const { path, direction } of this.#sorts) {
+          const aVal = getNestedValue(a, path);
+          const bVal = getNestedValue(b, path);
+          if (aVal === bVal) continue;
+          if (aVal == null) return direction === "asc" ? 1 : -1;
+          if (bVal == null) return direction === "asc" ? -1 : 1;
+          const cmp = aVal < bVal ? -1 : 1;
+          return direction === "asc" ? cmp : -cmp;
+        }
+        return 0;
+      });
+    }
+
+    // Apply pagination
+    if (this.#offset && this.#offset > 0) {
+      results = results.slice(this.#offset);
+    }
+    if (this.#limit !== undefined && this.#limit >= 0) {
+      results = results.slice(0, this.#limit);
+    }
+
+    // Bind serialize options from include() so toJSON() includes relationships
+    if (this.#include.length > 0) {
+      const opts = this.serializeOptions;
+      for (const instance of results) {
+        const original = (instance as any).toJSON;
+        (instance as any).toJSON = (overrides?: SerializeOptions) => {
+          const merged = { ...opts, ...overrides };
+          if (opts.related && overrides?.related) {
+            merged.related = [...new Set([...opts.related, ...overrides.related])];
+          }
+          return original(merged);
+        };
+      }
+    }
+
     return results;
   }
 

package/src/query/index.ts

@@ -3,3 +3,10 @@ export { QueryBuilder } from "./query-builder";
 export { operators } from "./operators";
 export type { Operator } from "./operators";
 export type { Condition } from "./query-builder";
+export {
+  queryDSLSchema,
+  parseWhereClause,
+  parseSortClause,
+  executeQueryDSL,
+} from "./query-dsl";
+export type { QueryDSL } from "./query-dsl";

package/src/query/query-dsl.ts

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import type { Collection } from "../collection";
+import type { Condition } from "./query-builder";
+import type { Operator } from "./operators";
+import { resolveModelDef } from "../api/helpers.js";
+
+// ---------------------------------------------------------------------------
+// Operator mapping: $dsl → internal
+// ---------------------------------------------------------------------------
+
+const OPERATOR_MAP: Record<string, Operator> = {
+  $eq: "eq",
+  $neq: "neq",
+  $in: "in",
+  $notIn: "notIn",
+  $gt: "gt",
+  $lt: "lt",
+  $gte: "gte",
+  $lte: "lte",
+  $contains: "contains",
+  $startsWith: "startsWith",
+  $endsWith: "endsWith",
+  $regex: "regex",
+  $exists: "exists",
+};
+
+const VALID_OPERATORS = new Set(Object.keys(OPERATOR_MAP));
+
+// ---------------------------------------------------------------------------
+// Security helpers
+// ---------------------------------------------------------------------------
+
+const FORBIDDEN_PATH_SEGMENTS = new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
+
+const MAX_REGEX_LENGTH = 200;
+
+function validatePath(path: string): void {
+  const segments = path.split(".");
+  for (const seg of segments) {
+    if (FORBIDDEN_PATH_SEGMENTS.has(seg)) {
+      throw new Error(
+        `Forbidden path segment "${seg}" in "${path}"`,
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema
+// ---------------------------------------------------------------------------
+
+const whereValueSchema: z.ZodType = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(z.unknown()),
+  z.record(z.string(), z.unknown()),
+]);
+
+const sortSchema = z.union([
+  z.record(z.string(), z.enum(["asc", "desc"])),
+  z.array(
+    z.object({
+      path: z.string(),
+      direction: z.enum(["asc", "desc"]).default("asc"),
+    }),
+  ),
+]);
+
+export const queryDSLSchema = z.object({
+  model: z.string(),
+  where: z.record(z.string(), whereValueSchema).optional(),
+  sort: sortSchema.optional(),
+  select: z.array(z.string()).optional(),
+  related: z.array(z.string()).optional(),
+  scopes: z.array(z.string()).optional(),
+  limit: z.number().int().min(0).optional(),
+  offset: z.number().int().min(0).optional(),
+  method: z
+    .enum(["fetchAll", "first", "last", "count"])
+    .default("fetchAll"),
+});
+
+export type QueryDSL = z.infer<typeof queryDSLSchema>;
+
+// ---------------------------------------------------------------------------
+// Parser: where object → Condition[]
+// ---------------------------------------------------------------------------
+
+export function parseWhereClause(
+  where: Record<string, unknown>,
+): Condition[] {
+  const conditions: Condition[] = [];
+
+  for (const [path, value] of Object.entries(where)) {
+    validatePath(path);
+
+    if (
+      value === null ||
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      // Literal → implicit $eq
+      conditions.push({ path, operator: "eq", value });
+    } else if (Array.isArray(value)) {
+      // Array → implicit $in
+      conditions.push({ path, operator: "in", value });
+    } else if (typeof value === "object" && value !== null) {
+      // Operator object: { "$gt": 5, "$lte": 10 }
+      for (const [opKey, opValue] of Object.entries(
+        value as Record<string, unknown>,
+      )) {
+        if (!VALID_OPERATORS.has(opKey)) {
+          throw new Error(
+            `Unknown operator: ${opKey}. Valid: ${[...VALID_OPERATORS].join(", ")}`,
+          );
+        }
+
+        const operator = OPERATOR_MAP[opKey];
+
+        // Regex length guard
+        if (
+          operator === "regex" &&
+          typeof opValue === "string" &&
+          opValue.length > MAX_REGEX_LENGTH
+        ) {
+          throw new Error(
+            `Regex pattern exceeds maximum length of ${MAX_REGEX_LENGTH} characters`,
+          );
+        }
+
+        conditions.push({ path, operator, value: opValue });
+      }
+    }
+  }
+
+  return conditions;
+}
+
+// ---------------------------------------------------------------------------
+// Parser: sort clause → SortSpec[]
+// ---------------------------------------------------------------------------
+
+export function parseSortClause(
+  sort: unknown,
+): Array<{ path: string; direction: "asc" | "desc" }> {
+  if (Array.isArray(sort)) {
+    return sort;
+  }
+  if (typeof sort === "object" && sort !== null) {
+    return Object.entries(sort as Record<string, string>).map(
+      ([path, direction]) => ({
+        path,
+        direction: direction as "asc" | "desc",
+      }),
+    );
+  }
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Select helper
+// ---------------------------------------------------------------------------
+
+function applySelect(
+  instance: any,
+  select?: string[],
+  related?: string[],
+): Record<string, unknown> {
+  const json = instance.toJSON({ related });
+  if (!select || select.length === 0) return json;
+
+  const filtered: Record<string, unknown> = {};
+  for (const key of select) {
+    if (key in json) {
+      filtered[key] = json[key];
+    } else if (key.startsWith("meta.") && json.meta) {
+      filtered[key] = json.meta[key.slice(5)];
+    }
+  }
+  return filtered;
+}
+
+// ---------------------------------------------------------------------------
+// Executor
+// ---------------------------------------------------------------------------
+
+export async function executeQueryDSL(
+  collection: Collection,
+  dsl: QueryDSL,
+) {
+  const def = resolveModelDef(collection, dsl.model);
+  if (!def) {
+    throw new Error(`Unknown model: ${dsl.model}`);
+  }
+
+  let q = collection.query(def);
+
+  // Apply scopes first
+  if (dsl.scopes) {
+    for (const name of dsl.scopes) {
+      q = q.scope(name);
+    }
+  }
+
+  // Apply where conditions
+  if (dsl.where) {
+    const conditions = parseWhereClause(dsl.where);
+    for (const cond of conditions) {
+      q = q.where(cond.path, cond.operator, cond.value);
+    }
+  }
+
+  // Apply sorts
+  if (dsl.sort) {
+    const sorts = parseSortClause(dsl.sort);
+    for (const { path, direction } of sorts) {
+      q = q.sort(path, direction);
+    }
+  }
+
+  // Apply pagination
+  if (dsl.limit !== undefined) {
+    q = q.limit(dsl.limit);
+  }
+  if (dsl.offset !== undefined) {
+    q = q.offset(dsl.offset);
+  }
+
+  // Execute based on method
+  switch (dsl.method) {
+    case "count":
+      return { count: await q.count() };
+
+    case "first": {
+      const result = await q.first();
+      return result ? applySelect(result, dsl.select, dsl.related) : null;
+    }
+
+    case "last": {
+      const result = await q.last();
+      return result ? applySelect(result, dsl.select, dsl.related) : null;
+    }
+
+    case "fetchAll":
+    default: {
+      const results = await q.fetchAll();
+      return results.map((instance: any) =>
+        applySelect(instance, dsl.select, dsl.related),
+      );
+    }
+  }
+}

package/src/relationships/has-many.ts

@@ -51,6 +51,7 @@ export class HasManyRelationship<
    */
   private extractChildNodes(): ChildNode[] {
     const { astQuery } = this.#document;
+    if (!this.#definition.heading) return [];
     const parentHeading = astQuery.findHeadingByText(this.#definition.heading);
     if (!parentHeading) return [];
 
@@ -100,6 +101,14 @@ export class HasManyRelationship<
 
   fetchAll(): InferModelInstance<TTarget>[] {
     const targetDef = this.#definition.target();
+
+    // Foreign key mode: query for target documents where meta[foreignKey] matches this document's slug
+    // Used when foreignKey is explicitly set, or when no heading is specified (convention-based)
+    if (this.#definition.foreignKey || !this.#definition.heading) {
+      return this.#fetchByForeignKey(targetDef);
+    }
+
+    // Heading mode: extract child nodes from parent document AST
     const childNodes = this.extractChildNodes();
 
     return childNodes.map(({ id, ast }) => {
@@ -119,6 +128,36 @@ export class HasManyRelationship<
     });
   }
 
+  #fetchByForeignKey(targetDef: TTarget): InferModelInstance<TTarget>[] {
+    // If foreignKey is explicitly set, use it. Otherwise infer from the parent document's model.
+    // Convention: look for meta[lowercase(parentModelName)] on target documents.
+    // e.g. Project hasMany Plans → looks for meta.project on Plan documents.
+    const fk = this.#definition.foreignKey || this.#inferForeignKey();
+    const slug = this.#document.slug;
+    const prefix = targetDef.prefix;
+    const results: InferModelInstance<TTarget>[] = [];
+
+    for (const pathId of this.#collection.available) {
+      if (!pathId.startsWith(prefix + "/")) continue;
+      const doc = this.#collection.document(pathId);
+      if (doc.meta[fk] === slug) {
+        results.push(this.#factory(doc, targetDef, this.#collection));
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Infer the foreign key name from the parent document's prefix.
+   * e.g. if the parent is in "projects/", the FK is "project" (singularized, lowercased).
+   */
+  #inferForeignKey(): string {
+    const parentPrefix = this.#document.id.split("/")[0];
+    // Simple singularize: strip trailing "s"
+    return parentPrefix.replace(/s$/, "");
+  }
+
   first(): InferModelInstance<TTarget> | undefined {
     return this.fetchAll()[0];
   }

package/src/relationships/index.ts

@@ -7,7 +7,10 @@ import type {
 
 /**
  * Declare a hasMany relationship.
- * Child models are extracted from sub-headings under a parent heading.
+ *
+ * Two modes:
+ * - `heading`: Children are extracted from sub-headings under a parent heading in the document.
+ * - `foreignKey`: Children are found by querying target documents where meta[foreignKey] matches this document's slug.
  *
  * The target parameter is a thunk (() => ModelDef) to allow circular references.
  */
@@ -16,7 +19,8 @@ export function hasMany<
 >(
   target: () => TTarget,
   options: {
-    heading: string;
+    heading?: string;
+    foreignKey?: string;
     meta?: (self: any) => Record<string, unknown>;
     id?: (slug: string) => string;
   }
@@ -25,6 +29,7 @@ export function hasMany<
     type: "hasMany",
     target,
     heading: options.heading,
+    foreignKey: options.foreignKey,
     meta: options.meta,
     id: options.id,
   };

package/src/section.ts

@@ -19,10 +19,12 @@ export function section<T>(
   options: {
     extract: (query: AstQuery) => T;
     schema?: z.ZodType<T>;
+    alternatives?: string[];
   }
 ): SectionDefinition<T> {
   return {
     heading,
+    alternatives: options.alternatives,
     extract: options.extract,
     schema: options.schema,
   };

package/src/types.ts

@@ -12,6 +12,7 @@ export interface CollectionItem {
   path: string;
   createdAt: Date;
   updatedAt: Date;
+  size: number;
 }
 
 /** Options when constructing a Collection */
@@ -19,6 +20,8 @@ export interface CollectionOptions {
   rootPath: string;
   extensions?: string[];
   name?: string;
+  /** When true (default), load() looks for a models.{ts,js,mjs} in rootPath and auto-registers exported model definitions. */
+  autoDiscover?: boolean;
 }
 
 // ─── Section system ───
@@ -30,6 +33,8 @@ export interface CollectionOptions {
 export interface SectionDefinition<T = unknown> {
   /** The heading text to find in the document */
   heading: string;
+  /** Alternative heading texts to try if the primary heading is not found */
+  alternatives?: string[];
   /** Extract structured data from the section's AST query */
   extract: (query: AstQuery) => T;
   /** Optional Zod schema to validate the extracted value */
@@ -43,7 +48,10 @@ export interface HasManyDefinition<
 > {
   type: "hasMany";
   target: () => TTarget;
-  heading: string;
+  /** Extract children from sub-headings under this heading in the parent document */
+  heading?: string;
+  /** Find children by querying for target documents where meta[foreignKey] matches this document's slug */
+  foreignKey?: string;
   meta?: (self: any) => Record<string, unknown>;
   id?: (slug: string) => string;
 }
@@ -80,7 +88,7 @@ export interface DocumentRef {
  */
 export interface ModelDefinition<
   TName extends string = string,
-  TMeta extends z.ZodTypeAny = z.ZodTypeAny,
+  TMeta extends z.ZodType = z.ZodType,
   TSections extends Record<string, SectionDefinition<any>> = Record<
     string,
     never
@@ -100,8 +108,17 @@ export interface ModelDefinition<
   sections: TSections;
   relationships: TRelationships;
   computed: TComputed;
+  /** Human-readable description of this model, auto-generated if not provided */
+  description: string;
+  /** Named scopes — reusable query presets */
+  scopes: Record<string, (query: any) => any>;
   match?: (doc: DocumentRef) => boolean;
   defaults?: Partial<z.input<TMeta>>;
+  pattern?: string | string[];
+  /** Glob patterns or RegExp to exclude matching pathIds from queries, listings, and TOC */
+  exclude?: (string | RegExp)[];
+  /** When true, documents are not required to have an H1 title */
+  titleOptional?: boolean;
 
   /** The inferred Zod schema for convenience (same as meta) */
   schema: TMeta;
@@ -131,6 +148,11 @@ export type InferModelInstance<
         readonly document: import("./document.js").Document;
         readonly collection: import("./collection.js").Collection;
 
+        // File metadata
+        readonly createdAt: Date | undefined;
+        readonly updatedAt: Date | undefined;
+        readonly size: number | undefined;
+
         // Typed meta from Zod schema
         readonly meta: z.infer<TMeta>;
 

package/src/utils/index.ts

@@ -9,3 +9,4 @@ export { stringifyAst } from "./stringify-ast";
 export { parseTable } from "./parse-table";
 export { normalizeHeadings } from "./normalize-headings";
 export { readDirectory } from "./read-directory";
+export { matchPattern, matchPatterns } from "./match-pattern";

package/src/utils/match-pattern.ts

@@ -0,0 +1,65 @@
+/**
+ * Express-style path pattern matching for extracting named parameters
+ * from document pathIds.
+ *
+ * Patterns use `:param` syntax for named segments and literal segments
+ * for exact matching. Segment counts must match exactly.
+ *
+ * Examples:
+ *   matchPattern("plans/:project/:slug", "plans/acme/launch")
+ *   // => { project: "acme", slug: "launch" }
+ *
+ *   matchPattern("plans/:project/:slug", "stories/acme/launch")
+ *   // => null (literal mismatch)
+ */
+
+/**
+ * Match a single pattern against a pathId.
+ * Returns extracted params on match, null on mismatch.
+ */
+export function matchPattern(
+  pattern: string,
+  pathId: string
+): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const pathParts = pathId.split("/").filter(Boolean);
+
+  if (patternParts.length !== pathParts.length) {
+    return null;
+  }
+
+  const params: Record<string, string> = {};
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const pat = patternParts[i];
+    const val = pathParts[i];
+
+    if (pat.startsWith(":")) {
+      params[pat.slice(1)] = val;
+    } else if (pat !== val) {
+      return null;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Try multiple patterns against a pathId, returning the first match.
+ * Accepts a single pattern string or an array of patterns.
+ */
+export function matchPatterns(
+  patterns: string | string[],
+  pathId: string
+): Record<string, string> | null {
+  const list = Array.isArray(patterns) ? patterns : [patterns];
+
+  for (const pattern of list) {
+    const result = matchPattern(pattern, pathId);
+    if (result !== null) {
+      return result;
+    }
+  }
+
+  return null;
+}