contentbase 0.0.2 → 0.0.5

package/src/document.ts

@@ -54,6 +54,7 @@ export class Document {
   }
 
   get title(): string {
+    if (this.#meta.title) return String(this.#meta.title);
     const heading = this.astQuery.select("heading");
     return heading ? toString(heading) : this.id;
   }
@@ -62,6 +63,18 @@ export class Document {
     return kebabCase(this.title.toLowerCase());
   }
 
+  get createdAt(): Date | undefined {
+    return this.collection.items.get(this.id)?.createdAt;
+  }
+
+  get updatedAt(): Date | undefined {
+    return this.collection.items.get(this.id)?.updatedAt;
+  }
+
+  get size(): number | undefined {
+    return this.collection.items.get(this.id)?.size;
+  }
+
   get rawContent(): string {
     if (Object.keys(this.#meta).length === 0) {
       return this.content;
@@ -71,7 +84,7 @@ export class Document {
   }
 
   get path(): string {
-    return this.collection.resolve(this.id) + ".mdx";
+    return this.collection.resolve(this.id) + ".md";
   }
 
   // ─── Processor ───
@@ -112,6 +125,11 @@ export class Document {
       heading = this.astQuery.findHeadingByText(startHeading) as
         | Content
         | undefined;
+
+      // If not found, try alternatives from the model definition's sections
+      if (!heading) {
+        heading = this.#resolveAlternativeHeading(startHeading);
+      }
     } else {
       heading = startHeading;
     }
@@ -128,6 +146,28 @@ export class Document {
     return [heading, ...sectionNodes];
   }
 
+  /**
+   * Look up section alternatives from the model definition.
+   * If the requested heading matches a section's heading or is one of its alternatives,
+   * try all variants (primary + alternatives) until one is found in the AST.
+   */
+  #resolveAlternativeHeading(requestedHeading: string): Content | undefined {
+    const def = this.collection?.findModelDefinition?.(this.id);
+    if (!def?.sections) return undefined;
+
+    for (const sectionDef of Object.values(def.sections) as any[]) {
+      const allNames = [sectionDef.heading, ...(sectionDef.alternatives ?? [])];
+      if (!allNames.some((n: string) => n === requestedHeading)) continue;
+
+      for (const name of allNames) {
+        const found = this.astQuery.findHeadingByText(name) as Content | undefined;
+        if (found) return found;
+      }
+    }
+
+    return undefined;
+  }
+
   /**
    * Returns an AstQuery scoped to the nodes underneath a particular heading,
    * excluding the heading itself.
@@ -388,12 +428,18 @@ export class Document {
     meta: Record<string, unknown>;
     content: string;
     ast: Root;
+    createdAt: Date | undefined;
+    updatedAt: Date | undefined;
+    size: number | undefined;
   } {
     return {
       id: this.id,
       meta: this.meta,
       content: this.content,
       ast: this.ast,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt,
+      size: this.size,
     };
   }
 

package/src/extract-sections.ts

@@ -62,7 +62,7 @@ function cloneAndShiftHeadings(
 ): RootContent[] {
   if (nodes.length === 0) return [];
 
-  const firstNode = nodes[0];
+  const firstNode = nodes[0]!;
   const originalDepth =
     firstNode.type === "heading" ? (firstNode as Heading).depth : 1;
   const depthShift = targetDepth - originalDepth;

package/src/index.ts

@@ -1,5 +1,6 @@
 // Core classes
-export { Collection } from "./collection";
+export { Collection, introspectMetaSchema } from "./collection";
+export type { FieldInfo } from "./collection";
 export { Document } from "./document";
 export { AstQuery } from "./ast-query";
 export { NodeShortcuts } from "./node-shortcuts";
@@ -13,13 +14,21 @@ export type {
 } from "./extract-sections";
 
 // defineModel and helpers
-export { defineModel } from "./define-model";
+export { defineModel, generateDescription } from "./define-model";
+export { Base } from "./base-model";
 export { section } from "./section";
 export { hasMany, belongsTo } from "./relationships/index";
 
 // Query
 export { CollectionQuery } from "./query/collection-query";
 export { QueryBuilder } from "./query/query-builder";
+export {
+  queryDSLSchema,
+  parseWhereClause,
+  parseSortClause,
+  executeQueryDSL,
+} from "./query/query-dsl";
+export type { QueryDSL } from "./query/query-dsl";
 
 // Model instance factory (advanced use)
 export { createModelInstance } from "./model-instance";
@@ -27,6 +36,9 @@ export { createModelInstance } from "./model-instance";
 // Validation
 export { validateDocument } from "./validator";
 
+// Pattern matching
+export { matchPattern, matchPatterns } from "./utils/match-pattern";
+
 import { toString } from "mdast-util-to-string";
 
 // Types

package/src/model-instance.ts

@@ -12,6 +12,7 @@ import type { Document } from "./document";
 import type { Collection } from "./collection";
 import { HasManyRelationship } from "./relationships/has-many";
 import { BelongsToRelationship } from "./relationships/belongs-to";
+import { matchPatterns } from "./utils/match-pattern";
 
 /**
  * Creates a model instance from a document and its model definition.
@@ -26,8 +27,11 @@ export function createModelInstance<
   definition: TDef,
   collection: Collection
 ): InferModelInstance<TDef> {
-  // ─── Meta: merge defaults, parse with Zod ───
-  const rawMeta = { ...(definition.defaults ?? {}), ...document.meta };
+  // ─── Meta: merge defaults, pattern-inferred values, then frontmatter ───
+  const patternMeta = definition.pattern
+    ? matchPatterns(definition.pattern, document.id) ?? {}
+    : {};
+  const rawMeta = { ...(definition.defaults ?? {}), ...patternMeta, ...document.meta };
   let meta: any;
   try {
     meta = definition.meta.parse(rawMeta);
@@ -46,7 +50,19 @@ export function createModelInstance<
       Object.defineProperty(sections, key, {
         get() {
           if (!cached) {
-            const sectionQuery = document.querySection(sd.heading);
+            let heading = sd.heading;
+            if (sd.alternatives?.length) {
+              const found = document.astQuery.findHeadingByText(heading);
+              if (!found) {
+                for (const alt of sd.alternatives) {
+                  if (document.astQuery.findHeadingByText(alt)) {
+                    heading = alt;
+                    break;
+                  }
+                }
+              }
+            }
+            const sectionQuery = document.querySection(heading);
             cached = { value: sd.extract(sectionQuery) };
           }
           return cached.value;
@@ -152,6 +168,9 @@ export function createModelInstance<
       id: document.id,
       title: document.title,
       meta,
+      createdAt: document.createdAt,
+      updatedAt: document.updatedAt,
+      size: document.size,
     };
 
     // Include requested sections
@@ -198,8 +217,15 @@ export function createModelInstance<
     get slug() {
       return document.slug;
     },
-    document,
-    collection,
+    get createdAt() {
+      return document.createdAt;
+    },
+    get updatedAt() {
+      return document.updatedAt;
+    },
+    get size() {
+      return document.size;
+    },
     meta,
     sections,
     relationships,
@@ -223,5 +249,9 @@ export function createModelInstance<
     },
   };
 
+  // Keep heavy back-references accessible but out of REPL output
+  Object.defineProperty(instance, "document", { value: document, enumerable: false });
+  Object.defineProperty(instance, "collection", { value: collection, enumerable: false });
+
   return instance as InferModelInstance<TDef>;
 }

package/src/node-shortcuts.ts

@@ -50,7 +50,7 @@ export class NodeShortcuts {
     return this.headings.reduce(
       (memo, heading) => {
         memo[heading.depth] = memo[heading.depth] || [];
-        memo[heading.depth].push(heading);
+        memo[heading.depth]!.push(heading);
         return memo;
       },
       {} as Record<number, Heading[]>

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),
+      );
+    }
+  }
+}