contentbase 0.0.1

package/src/model-instance.ts

@@ -0,0 +1,227 @@
+import { z } from "zod";
+import type {
+  ModelDefinition,
+  InferModelInstance,
+  SectionDefinition,
+  HasManyDefinition,
+  BelongsToDefinition,
+  ValidationResult,
+  SerializeOptions,
+} from "./types";
+import type { Document } from "./document";
+import type { Collection } from "./collection";
+import { HasManyRelationship } from "./relationships/has-many";
+import { BelongsToRelationship } from "./relationships/belongs-to";
+
+/**
+ * Creates a model instance from a document and its model definition.
+ *
+ * This is the central factory function. Every typed model instance
+ * in contentbase is created here.
+ */
+export function createModelInstance<
+  TDef extends ModelDefinition<any, any, any, any, any>,
+>(
+  document: Document,
+  definition: TDef,
+  collection: Collection
+): InferModelInstance<TDef> {
+  // ─── Meta: merge defaults, parse with Zod ───
+  const rawMeta = { ...(definition.defaults ?? {}), ...document.meta };
+  let meta: any;
+  try {
+    meta = definition.meta.parse(rawMeta);
+  } catch (e) {
+    // If parsing fails, use raw meta so the instance can still be created
+    // Validation will catch the errors later
+    meta = rawMeta;
+  }
+
+  // ─── Sections: lazy extraction via defineProperty ───
+  const sections = {} as Record<string, unknown>;
+  if (definition.sections) {
+    for (const [key, sectionDef] of Object.entries(definition.sections)) {
+      const sd = sectionDef as SectionDefinition<unknown>;
+      let cached: { value: unknown } | null = null;
+      Object.defineProperty(sections, key, {
+        get() {
+          if (!cached) {
+            const sectionQuery = document.querySection(sd.heading);
+            cached = { value: sd.extract(sectionQuery) };
+          }
+          return cached.value;
+        },
+        enumerable: true,
+        configurable: true,
+      });
+    }
+  }
+
+  // ─── Relationships: create accessor objects ───
+  const relationships = {} as Record<string, unknown>;
+  if (definition.relationships) {
+    for (const [key, relDef] of Object.entries(definition.relationships)) {
+      if ((relDef as any).type === "hasMany") {
+        const hm = relDef as HasManyDefinition<any>;
+        relationships[key] = new HasManyRelationship(
+          document,
+          collection,
+          hm,
+          createModelInstance
+        );
+      } else if ((relDef as any).type === "belongsTo") {
+        const bt = relDef as BelongsToDefinition<any>;
+        relationships[key] = new BelongsToRelationship(
+          document,
+          collection,
+          bt,
+          createModelInstance
+        );
+      }
+    }
+  }
+
+  // ─── Computed: lazy getters ───
+  const computed = {} as Record<string, unknown>;
+  const selfProxy = {
+    meta,
+    sections,
+    relationships,
+    document,
+    id: document.id,
+    title: document.title,
+    slug: document.slug,
+  };
+
+  if (definition.computed) {
+    for (const [key, fn] of Object.entries(definition.computed)) {
+      Object.defineProperty(computed, key, {
+        get() {
+          return (fn as Function)(selfProxy);
+        },
+        enumerable: true,
+        configurable: true,
+      });
+    }
+  }
+
+  // ─── Validation ───
+  const errors = new Map<string, z.ZodIssue>();
+
+  async function validate(): Promise<ValidationResult> {
+    errors.clear();
+
+    // Validate meta
+    const metaResult = definition.meta.safeParse(rawMeta);
+    if (!metaResult.success) {
+      for (const issue of metaResult.error.issues) {
+        errors.set(issue.path.join(".") || "meta", issue);
+      }
+    }
+
+    // Validate sections that have schemas
+    if (definition.sections) {
+      for (const [key, sd] of Object.entries(definition.sections)) {
+        const sectionDef = sd as SectionDefinition<unknown>;
+        if (sectionDef.schema) {
+          const sectionData = (sections as any)[key];
+          const sResult = sectionDef.schema.safeParse(sectionData);
+          if (!sResult.success) {
+            for (const issue of sResult.error.issues) {
+              errors.set(
+                `sections.${key}.${issue.path.join(".")}`,
+                issue
+              );
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      valid: errors.size === 0,
+      errors: Array.from(errors.values()),
+    };
+  }
+
+  // ─── toJSON ───
+  function toJSON(
+    options: SerializeOptions = {}
+  ): Record<string, unknown> {
+    const json: Record<string, unknown> = {
+      id: document.id,
+      title: document.title,
+      meta,
+    };
+
+    // Include requested sections
+    if (options.sections) {
+      for (const key of options.sections) {
+        if (key in sections) {
+          json[key] = (sections as any)[key];
+        }
+      }
+    }
+
+    // Include requested computed values
+    if (options.computed) {
+      for (const key of options.computed) {
+        if (key in computed) {
+          json[key] = (computed as any)[key];
+        }
+      }
+    }
+
+    // Include requested relationships
+    if (options.related) {
+      for (const key of options.related) {
+        const rel = (relationships as any)[key];
+        if (!rel) continue;
+
+        if ("fetchAll" in rel) {
+          json[key] = rel.fetchAll().map((inst: any) => inst.toJSON());
+        } else if ("fetch" in rel) {
+          json[key] = rel.fetch().toJSON();
+        }
+      }
+    }
+
+    return json;
+  }
+
+  // ─── Assemble the instance ───
+  const instance = {
+    id: document.id,
+    get title() {
+      return document.title;
+    },
+    get slug() {
+      return document.slug;
+    },
+    document,
+    collection,
+    meta,
+    sections,
+    relationships,
+    computed,
+    errors,
+    get hasErrors() {
+      return errors.size > 0;
+    },
+    validate,
+    toJSON,
+    async runAction(
+      name: string,
+      opts: Record<string, unknown> = {}
+    ) {
+      const actionFn = collection.actions.get(name);
+      if (!actionFn) throw new Error(`Action "${name}" not found`);
+      return actionFn(collection, instance, opts);
+    },
+    async save(opts = {}) {
+      await document.save(opts);
+    },
+  };
+
+  return instance as InferModelInstance<TDef>;
+}

package/src/node-shortcuts.ts

@@ -0,0 +1,87 @@
+import { parseTable } from "./utils/parse-table";
+import type { AstQuery } from "./ast-query";
+import type { Content, Heading } from "mdast";
+
+/**
+ * Convenience getters for common node queries on a document.
+ */
+export class NodeShortcuts {
+  #astQuery: AstQuery;
+
+  constructor(astQuery: AstQuery) {
+    this.#astQuery = astQuery;
+  }
+
+  get first(): Content | undefined {
+    return this.#astQuery.ast.children[0] as Content | undefined;
+  }
+
+  get last(): Content | undefined {
+    const children = this.#astQuery.ast.children;
+    return children[children.length - 1] as Content | undefined;
+  }
+
+  get headings(): Heading[] {
+    return this.#astQuery.selectAll("heading") as Heading[];
+  }
+
+  get firstHeading(): Heading | undefined {
+    return this.headings[0];
+  }
+
+  get secondHeading(): Heading | undefined {
+    return this.headings[1];
+  }
+
+  get lastHeading(): Heading | undefined {
+    return this.headings[this.headings.length - 1];
+  }
+
+  get leadingElementsAfterTitle(): Content[] {
+    const { firstHeading, secondHeading } = this;
+    if (!firstHeading) return [];
+    if (secondHeading) {
+      return this.#astQuery.findBetween(firstHeading, secondHeading);
+    }
+    return this.#astQuery.findAllAfter(firstHeading);
+  }
+
+  get headingsByDepth(): Record<number, Heading[]> {
+    return this.headings.reduce(
+      (memo, heading) => {
+        memo[heading.depth] = memo[heading.depth] || [];
+        memo[heading.depth].push(heading);
+        return memo;
+      },
+      {} as Record<number, Heading[]>
+    );
+  }
+
+  get links(): Content[] {
+    return this.#astQuery.selectAll("link");
+  }
+
+  get tables(): Content[] {
+    return this.#astQuery.selectAll("table");
+  }
+
+  get tablesAsData(): Record<string, string>[][] {
+    return this.tables.map((table) => parseTable(table));
+  }
+
+  get paragraphs(): Content[] {
+    return this.#astQuery.selectAll("paragraph");
+  }
+
+  get lists(): Content[] {
+    return this.#astQuery.selectAll("list");
+  }
+
+  get codeBlocks(): Content[] {
+    return this.#astQuery.selectAll("code");
+  }
+
+  get images(): Content[] {
+    return this.#astQuery.selectAll("image");
+  }
+}

package/src/parse.ts

@@ -0,0 +1,123 @@
+import fs from "fs/promises";
+import matter from "gray-matter";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import { toString } from "mdast-util-to-string";
+import { AstQuery } from "./ast-query";
+import { NodeShortcuts } from "./node-shortcuts";
+import { stringifyAst } from "./utils/stringify-ast";
+import type { Root, Content, RootContent } from "mdast";
+
+const processor = unified().use(remarkParse).use(remarkGfm);
+
+export interface ParsedDocument {
+  /** YAML frontmatter key/values */
+  meta: Record<string, unknown>;
+  /** Markdown content (without frontmatter) */
+  content: string;
+  /** The MDAST root node */
+  ast: Root;
+  /** Queryable AST wrapper */
+  astQuery: AstQuery;
+  /** Convenience node accessors */
+  nodes: NodeShortcuts;
+  /** First heading text, or empty string */
+  title: string;
+  /** Stringify an AST back to markdown */
+  stringify(ast?: Root): string;
+  /** Extract a section by heading text */
+  extractSection(heading: string | Content): Content[];
+  /** Get a queryable AstQuery scoped to a section */
+  querySection(heading: string | Content): AstQuery;
+}
+
+/**
+ * Parse a markdown/MDX file or raw string into a queryable document.
+ *
+ * @param input - A file path (.md/.mdx) or raw markdown string
+ * @returns A ParsedDocument with AST query capabilities
+ *
+ * @example
+ * ```ts
+ * import { parse } from "contentbase";
+ *
+ * const doc = await parse("./content/my-post.mdx");
+ * doc.meta           // frontmatter
+ * doc.astQuery.selectAll("heading")
+ * doc.nodes.tables
+ * doc.querySection("Introduction").selectAll("paragraph")
+ * ```
+ */
+export async function parse(input: string): Promise<ParsedDocument> {
+  let raw: string;
+
+  if (looksLikeFilePath(input)) {
+    raw = await fs.readFile(input, "utf-8");
+  } else {
+    raw = input;
+  }
+
+  const { data: meta, content } = matter(raw);
+  const ast = processor.parse(content);
+  const astQuery = new AstQuery(ast);
+  const nodes = new NodeShortcuts(astQuery);
+
+  const firstHeading = astQuery.select("heading");
+  const title = firstHeading ? toString(firstHeading) : "";
+
+  function extractSection(startHeading: string | Content): Content[] {
+    let heading: Content | undefined;
+    if (typeof startHeading === "string") {
+      heading = astQuery.findHeadingByText(startHeading) as Content | undefined;
+    } else {
+      heading = startHeading;
+    }
+    if (!heading) {
+      throw new Error(
+        `Heading not found: ${typeof startHeading === "string" ? startHeading : toString(startHeading)}`
+      );
+    }
+
+    const endHeading = astQuery.findNextSiblingHeadingTo(heading as any);
+    const sectionNodes = endHeading
+      ? astQuery.findBetween(heading, endHeading)
+      : astQuery.findAllAfter(heading);
+    return [heading, ...sectionNodes];
+  }
+
+  function querySection(startHeading: string | Content): AstQuery {
+    let children: Content[] = [];
+    try {
+      children = extractSection(startHeading).slice(1);
+    } catch {
+      // Section not found: return empty query
+    }
+    return new AstQuery({
+      type: "root",
+      children: children as RootContent[],
+    });
+  }
+
+  return {
+    meta,
+    content,
+    ast,
+    astQuery,
+    nodes,
+    title,
+    stringify: (tree: Root = ast) => stringifyAst(tree),
+    extractSection,
+    querySection,
+  };
+}
+
+function looksLikeFilePath(input: string): boolean {
+  // If it contains a newline, it's raw markdown
+  if (input.includes("\n")) return false;
+  // If it ends with a markdown extension, it's a path
+  if (/\.mdx?$/i.test(input)) return true;
+  // If it starts with . or / or ~, treat as path
+  if (/^[.\/~]/.test(input)) return true;
+  return false;
+}

package/src/query/collection-query.ts

@@ -0,0 +1,149 @@
+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";
+
+/**
+ * CollectionQuery is a typed query builder for a specific model type.
+ * Results are typed as InferModelInstance<TDef>[].
+ *
+ * Usage:
+ *   const results = await collection
+ *     .query(Epic)
+ *     .where("meta.priority", "high")
+ *     .fetchAll();
+ */
+export class CollectionQuery<
+  TDef extends ModelDefinition<any, any, any, any, any>,
+> {
+  #collection: Collection;
+  #definition: TDef;
+  #queryBuilder: QueryBuilder;
+
+  constructor(collection: Collection, definition: TDef) {
+    this.#collection = collection;
+    this.#definition = definition;
+    this.#queryBuilder = new QueryBuilder();
+  }
+
+  where(
+    pathOrObject: string | Record<string, unknown>,
+    operatorOrValue?: any,
+    value?: any
+  ): this {
+    this.#queryBuilder.where(pathOrObject, operatorOrValue, value);
+    return this;
+  }
+
+  whereIn(path: string, values: unknown[]): this {
+    this.#queryBuilder.whereIn(path, values);
+    return this;
+  }
+
+  whereNotIn(path: string, values: unknown[]): this {
+    this.#queryBuilder.whereNotIn(path, values);
+    return this;
+  }
+
+  whereGt(path: string, value: unknown): this {
+    this.#queryBuilder.whereGt(path, value);
+    return this;
+  }
+
+  whereLt(path: string, value: unknown): this {
+    this.#queryBuilder.whereLt(path, value);
+    return this;
+  }
+
+  whereGte(path: string, value: unknown): this {
+    this.#queryBuilder.whereGte(path, value);
+    return this;
+  }
+
+  whereLte(path: string, value: unknown): this {
+    this.#queryBuilder.whereLte(path, value);
+    return this;
+  }
+
+  whereContains(path: string, value: string): this {
+    this.#queryBuilder.whereContains(path, value);
+    return this;
+  }
+
+  whereStartsWith(path: string, value: string): this {
+    this.#queryBuilder.whereStartsWith(path, value);
+    return this;
+  }
+
+  whereEndsWith(path: string, value: string): this {
+    this.#queryBuilder.whereEndsWith(path, value);
+    return this;
+  }
+
+  whereRegex(path: string, pattern: RegExp | string): this {
+    this.#queryBuilder.whereRegex(path, pattern);
+    return this;
+  }
+
+  whereExists(path: string): this {
+    this.#queryBuilder.whereExists(path);
+    return this;
+  }
+
+  whereNotExists(path: string): this {
+    this.#queryBuilder.whereNotExists(path);
+    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>[] = [];
+
+    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;
+
+      const doc = collection.document(pathId);
+      const instance = createModelInstance(doc, definition, collection);
+
+      // Apply query conditions
+      const passesAll = conditions.every((cond) => {
+        const actual = getNestedValue(instance, cond.path);
+        return operators[cond.operator](actual, cond.value);
+      });
+
+      if (passesAll) {
+        results.push(instance);
+      }
+    }
+
+    return results;
+  }
+
+  async first(): Promise<InferModelInstance<TDef> | undefined> {
+    return (await this.fetchAll())[0];
+  }
+
+  async last(): Promise<InferModelInstance<TDef> | undefined> {
+    const all = await this.fetchAll();
+    return all[all.length - 1];
+  }
+
+  async count(): Promise<number> {
+    return (await this.fetchAll()).length;
+  }
+}
+
+function getNestedValue(obj: any, path: string): unknown {
+  return path.split(".").reduce((acc, key) => acc?.[key], obj);
+}

package/src/query/index.ts

@@ -0,0 +1,5 @@
+export { CollectionQuery } from "./collection-query";
+export { QueryBuilder } from "./query-builder";
+export { operators } from "./operators";
+export type { Operator } from "./operators";
+export type { Condition } from "./query-builder";

package/src/query/operators.ts

@@ -0,0 +1,37 @@
+export type Operator =
+  | "eq"
+  | "neq"
+  | "in"
+  | "notIn"
+  | "gt"
+  | "lt"
+  | "gte"
+  | "lte"
+  | "contains"
+  | "startsWith"
+  | "endsWith"
+  | "regex"
+  | "exists";
+
+export const operators: Record<
+  Operator,
+  (actual: any, expected: any) => boolean
+> = {
+  eq: (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b),
+  neq: (a, b) => !operators.eq(a, b),
+  in: (a, b) => Array.isArray(b) && b.includes(a),
+  notIn: (a, b) => Array.isArray(b) && !b.includes(a),
+  gt: (a, b) => a > b,
+  lt: (a, b) => a < b,
+  gte: (a, b) => a >= b,
+  lte: (a, b) => a <= b,
+  contains: (a, b) => typeof a === "string" && a.includes(b),
+  startsWith: (a, b) => typeof a === "string" && a.startsWith(b),
+  endsWith: (a, b) => typeof a === "string" && a.endsWith(b),
+  regex: (a, b) =>
+    b instanceof RegExp
+      ? b.test(String(a))
+      : new RegExp(b).test(String(a)),
+  exists: (a, b) =>
+    b ? a !== undefined && a !== null : a === undefined || a === null,
+};