contentbase 0.0.1

package/src/query/query-builder.ts

@@ -0,0 +1,109 @@
+import type { Operator } from "./operators";
+
+export interface Condition {
+  path: string;
+  operator: Operator;
+  value: unknown;
+}
+
+export class QueryBuilder {
+  #conditions: Condition[] = [];
+
+  get conditions(): Condition[] {
+    return [...this.#conditions];
+  }
+
+  /**
+   * Add a where condition.
+   *
+   * Three call signatures:
+   *   where({ "meta.status": "active" })         -- object shorthand, implicit eq
+   *   where("meta.status", "active")              -- two args, implicit eq
+   *   where("meta.priority", "gt", 5)             -- three args, explicit operator
+   *
+   * Always returns `this` for chaining (fixes bug in original).
+   */
+  where(
+    pathOrObject: string | Record<string, unknown>,
+    operatorOrValue?: Operator | unknown,
+    value?: unknown
+  ): this {
+    if (typeof pathOrObject === "object" && pathOrObject !== null) {
+      for (const [k, v] of Object.entries(pathOrObject)) {
+        this.#conditions.push({ path: k, operator: "eq", value: v });
+      }
+      return this;
+    }
+
+    if (value === undefined) {
+      // Two-arg form: where("path", value) -- implicit eq
+      this.#conditions.push({
+        path: pathOrObject,
+        operator: "eq",
+        value: operatorOrValue,
+      });
+    } else {
+      // Three-arg form: where("path", operator, value)
+      this.#conditions.push({
+        path: pathOrObject,
+        operator: operatorOrValue as Operator,
+        value,
+      });
+    }
+    return this;
+  }
+
+  whereIn(path: string, values: unknown[]): this {
+    this.#conditions.push({
+      path,
+      operator: "in",
+      value: values.filter(Boolean),
+    });
+    return this;
+  }
+
+  whereNotIn(path: string, values: unknown[]): this {
+    this.#conditions.push({ path, operator: "notIn", value: values });
+    return this;
+  }
+
+  whereGt(path: string, value: unknown): this {
+    return this.where(path, "gt", value);
+  }
+
+  whereLt(path: string, value: unknown): this {
+    return this.where(path, "lt", value);
+  }
+
+  whereGte(path: string, value: unknown): this {
+    return this.where(path, "gte", value);
+  }
+
+  whereLte(path: string, value: unknown): this {
+    return this.where(path, "lte", value);
+  }
+
+  whereContains(path: string, value: string): this {
+    return this.where(path, "contains", value);
+  }
+
+  whereStartsWith(path: string, value: string): this {
+    return this.where(path, "startsWith", value);
+  }
+
+  whereEndsWith(path: string, value: string): this {
+    return this.where(path, "endsWith", value);
+  }
+
+  whereRegex(path: string, pattern: RegExp | string): this {
+    return this.where(path, "regex", pattern);
+  }
+
+  whereExists(path: string): this {
+    return this.where(path, "exists", true);
+  }
+
+  whereNotExists(path: string): this {
+    return this.where(path, "exists", false);
+  }
+}

package/src/relationships/belongs-to.ts

@@ -0,0 +1,50 @@
+import type { Document } from "../document";
+import type { Collection } from "../collection";
+import type {
+  BelongsToDefinition,
+  ModelDefinition,
+  InferModelInstance,
+  BelongsToAccessor,
+  ModelInstanceFactory,
+} from "../types";
+
+export class BelongsToRelationship<
+  TTarget extends ModelDefinition<any, any, any, any, any>,
+> implements BelongsToAccessor<TTarget>
+{
+  #document: Document;
+  #collection: Collection;
+  #definition: BelongsToDefinition<TTarget>;
+  #factory: ModelInstanceFactory;
+
+  constructor(
+    document: Document,
+    collection: Collection,
+    definition: BelongsToDefinition<TTarget>,
+    factory: ModelInstanceFactory
+  ) {
+    this.#document = document;
+    this.#collection = collection;
+    this.#definition = definition;
+    this.#factory = factory;
+  }
+
+  fetch(): InferModelInstance<TTarget> {
+    const targetDef = this.#definition.target();
+    const foreignKeyValue = this.#definition.foreignKey({
+      id: this.#document.id,
+      meta: this.#document.meta,
+    });
+
+    const relatedId = `${targetDef.prefix}/${foreignKeyValue}`;
+
+    if (!this.#collection.items.has(relatedId)) {
+      throw new Error(
+        `Could not find ${targetDef.name} with id "${relatedId}"`
+      );
+    }
+
+    const doc = this.#collection.document(relatedId);
+    return this.#factory(doc, targetDef, this.#collection);
+  }
+}

package/src/relationships/has-many.ts

@@ -0,0 +1,136 @@
+import { toString } from "mdast-util-to-string";
+import { kebabCase } from "../utils/inflect";
+import type { Document } from "../document";
+import type { Collection } from "../collection";
+import type {
+  HasManyDefinition,
+  ModelDefinition,
+  InferModelInstance,
+  HasManyAccessor,
+  ModelInstanceFactory,
+} from "../types";
+import type { Root, Heading, Content, RootContent } from "mdast";
+
+interface ChildNode {
+  title: string;
+  id: string;
+  ast: Root;
+  section: Content[];
+}
+
+export class HasManyRelationship<
+  TTarget extends ModelDefinition<any, any, any, any, any>,
+> implements HasManyAccessor<TTarget>
+{
+  #document: Document;
+  #collection: Collection;
+  #definition: HasManyDefinition<TTarget>;
+  #factory: ModelInstanceFactory;
+
+  constructor(
+    document: Document,
+    collection: Collection,
+    definition: HasManyDefinition<TTarget>,
+    factory: ModelInstanceFactory
+  ) {
+    this.#document = document;
+    this.#collection = collection;
+    this.#definition = definition;
+    this.#factory = factory;
+  }
+
+  /**
+   * Extract child nodes from the document AST.
+   *
+   * Algorithm (matching the original):
+   * 1. Find the parent heading by text (e.g., "Stories")
+   * 2. Extract the section under that heading
+   * 3. Filter for child headings at depth = parentHeading.depth + 1
+   * 4. For each child heading, extract its sub-section
+   * 5. Compute an ID from the parent title and child slug
+   */
+  private extractChildNodes(): ChildNode[] {
+    const { astQuery } = this.#document;
+    const parentHeading = astQuery.findHeadingByText(this.#definition.heading);
+    if (!parentHeading) return [];
+
+    const sectionNodes = this.#document
+      .extractSection(parentHeading as Content)
+      .slice(1);
+
+    const childDepth = (parentHeading as Heading).depth + 1;
+
+    // Get all child headings at the expected depth
+    const childHeadings = sectionNodes.filter(
+      (n: any) => n.type === "heading" && n.depth === childDepth
+    );
+
+    return childHeadings.map((heading: any) => {
+      // For each child heading, find its sub-section
+      // (from this heading to the next heading at the same depth, or end of parent section)
+      const headingIdx = sectionNodes.indexOf(heading);
+      const nextIdx = sectionNodes.findIndex(
+        (n: any, i: number) =>
+          i > headingIdx && n.type === "heading" && n.depth === childDepth
+      );
+      const section =
+        nextIdx === -1
+          ? sectionNodes.slice(headingIdx)
+          : sectionNodes.slice(headingIdx, nextIdx);
+
+      const title = toString(heading);
+      const slug = kebabCase(title.toLowerCase());
+      const targetDef = this.#definition.target();
+
+      const id = this.#definition.id
+        ? this.#definition.id(slug)
+        : `${targetDef.prefix}/${kebabCase(this.#document.title.toLowerCase())}/${slug}`;
+
+      return {
+        title,
+        id,
+        section,
+        ast: {
+          type: "root" as const,
+          children: section as RootContent[],
+        },
+      };
+    });
+  }
+
+  fetchAll(): InferModelInstance<TTarget>[] {
+    const targetDef = this.#definition.target();
+    const childNodes = this.extractChildNodes();
+
+    return childNodes.map(({ id, ast }) => {
+      // If the document already exists in the collection, use it
+      if (this.#collection.items.has(id)) {
+        const doc = this.#collection.document(id);
+        return this.#factory(doc, targetDef, this.#collection);
+      }
+
+      // Otherwise create an in-memory document from the extracted AST
+      const doc = this.#collection.createDocument({
+        id,
+        meta: this.#definition.meta ? this.#definition.meta({}) : {},
+        ast: ast as Root,
+      });
+      return this.#factory(doc, targetDef, this.#collection);
+    });
+  }
+
+  first(): InferModelInstance<TTarget> | undefined {
+    return this.fetchAll()[0];
+  }
+
+  last(): InferModelInstance<TTarget> | undefined {
+    const all = this.fetchAll();
+    return all[all.length - 1];
+  }
+
+  async create(): Promise<InferModelInstance<TTarget>[]> {
+    const models = this.fetchAll();
+    await Promise.all(models.map((m: any) => m.save()));
+    return models;
+  }
+}

package/src/relationships/index.ts

@@ -0,0 +1,57 @@
+import type {
+  HasManyDefinition,
+  BelongsToDefinition,
+  ModelDefinition,
+  DocumentRef,
+} from "../types";
+
+/**
+ * Declare a hasMany relationship.
+ * Child models are extracted from sub-headings under a parent heading.
+ *
+ * The target parameter is a thunk (() => ModelDef) to allow circular references.
+ */
+export function hasMany<
+  TTarget extends ModelDefinition<any, any, any, any, any>,
+>(
+  target: () => TTarget,
+  options: {
+    heading: string;
+    meta?: (self: any) => Record<string, unknown>;
+    id?: (slug: string) => string;
+  }
+): HasManyDefinition<TTarget> {
+  return {
+    type: "hasMany",
+    target,
+    heading: options.heading,
+    meta: options.meta,
+    id: options.id,
+  };
+}
+
+/**
+ * Declare a belongsTo relationship.
+ * The foreign key function receives a DocumentRef (with id and meta)
+ * and returns the id fragment of the parent.
+ */
+export function belongsTo<
+  TTarget extends ModelDefinition<any, any, any, any, any>,
+>(
+  target: () => TTarget,
+  options: {
+    foreignKey: (doc: DocumentRef) => string;
+  }
+): BelongsToDefinition<TTarget> {
+  return {
+    type: "belongsTo",
+    target,
+    foreignKey: options.foreignKey,
+  };
+}
+
+export type {
+  HasManyDefinition,
+  BelongsToDefinition,
+  RelationshipDefinition,
+} from "../types";

package/src/relationships/types.ts

@@ -0,0 +1,7 @@
+export type {
+  HasManyDefinition,
+  BelongsToDefinition,
+  RelationshipDefinition,
+  HasManyAccessor,
+  BelongsToAccessor,
+} from "../types";

package/src/section.ts

@@ -0,0 +1,29 @@
+import type { z } from "zod";
+import type { AstQuery } from "./ast-query";
+import type { SectionDefinition } from "./types";
+
+/**
+ * Helper function to create a SectionDefinition with proper type inference.
+ * The generic T is inferred from the extract function's return type.
+ *
+ * Without this helper, TypeScript would widen the return type of extract to `unknown`.
+ *
+ * Usage:
+ *   section("Acceptance Criteria", {
+ *     extract: (query) => query.selectAll("listItem").map(toString),
+ *     schema: z.array(z.string()).min(1),
+ *   })
+ */
+export function section<T>(
+  heading: string,
+  options: {
+    extract: (query: AstQuery) => T;
+    schema?: z.ZodType<T>;
+  }
+): SectionDefinition<T> {
+  return {
+    heading,
+    extract: options.extract,
+    schema: options.schema,
+  };
+}

package/src/types.ts

@@ -0,0 +1,221 @@
+import type { z } from "zod";
+import type { Root } from "mdast";
+import type { AstQuery } from "./ast-query";
+
+// ─── Fundamental types ───
+
+/** The raw item stored in Collection.items before a Document is created */
+export interface CollectionItem {
+  raw: string;
+  content: string;
+  meta: Record<string, unknown>;
+  path: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Options when constructing a Collection */
+export interface CollectionOptions {
+  rootPath: string;
+  extensions?: string[];
+  name?: string;
+}
+
+// ─── Section system ───
+
+/**
+ * A section definition declares how to extract structured data from
+ * a heading-based section of a document.
+ */
+export interface SectionDefinition<T = unknown> {
+  /** The heading text to find in the document */
+  heading: string;
+  /** Extract structured data from the section's AST query */
+  extract: (query: AstQuery) => T;
+  /** Optional Zod schema to validate the extracted value */
+  schema?: z.ZodType<T>;
+}
+
+// ─── Relationship system ───
+
+export interface HasManyDefinition<
+  TTarget extends ModelDefinition<any, any, any, any, any> = any,
+> {
+  type: "hasMany";
+  target: () => TTarget;
+  heading: string;
+  meta?: (self: any) => Record<string, unknown>;
+  id?: (slug: string) => string;
+}
+
+export interface BelongsToDefinition<
+  TTarget extends ModelDefinition<any, any, any, any, any> = any,
+> {
+  type: "belongsTo";
+  target: () => TTarget;
+  foreignKey: (doc: DocumentRef) => string;
+}
+
+export type RelationshipDefinition<
+  TTarget extends ModelDefinition<any, any, any, any, any> = any,
+> = HasManyDefinition<TTarget> | BelongsToDefinition<TTarget>;
+
+/** A minimal document reference for relationship foreign key functions */
+export interface DocumentRef {
+  id: string;
+  meta: Record<string, unknown>;
+}
+
+// ─── Model Definition (the config object) ───
+
+/**
+ * ModelDefinition is the static config object produced by defineModel().
+ * It carries all type parameters needed to fully type a model instance.
+ *
+ * TName - string literal type for the model name
+ * TMeta - the Zod schema type for frontmatter metadata
+ * TSections - record of section definitions
+ * TRelationships - record of relationship definitions
+ * TComputed - record of computed property functions
+ */
+export interface ModelDefinition<
+  TName extends string = string,
+  TMeta extends z.ZodTypeAny = z.ZodTypeAny,
+  TSections extends Record<string, SectionDefinition<any>> = Record<
+    string,
+    never
+  >,
+  TRelationships extends Record<string, RelationshipDefinition<any>> = Record<
+    string,
+    never
+  >,
+  TComputed extends Record<string, (self: any) => any> = Record<
+    string,
+    never
+  >,
+> {
+  readonly name: TName;
+  prefix: string;
+  meta: TMeta;
+  sections: TSections;
+  relationships: TRelationships;
+  computed: TComputed;
+  match?: (doc: DocumentRef) => boolean;
+  defaults?: Partial<z.input<TMeta>>;
+
+  /** The inferred Zod schema for convenience (same as meta) */
+  schema: TMeta;
+}
+
+// ─── Model Instance (the runtime object) ───
+
+/**
+ * InferModelInstance takes a ModelDefinition and produces the shape
+ * of the runtime model instance.
+ */
+export type InferModelInstance<
+  TDef extends ModelDefinition<any, any, any, any, any>,
+> =
+  TDef extends ModelDefinition<
+    infer _TName,
+    infer TMeta,
+    infer TSections,
+    infer TRelationships,
+    infer TComputed
+  >
+    ? {
+        // Core properties
+        readonly id: string;
+        readonly title: string;
+        readonly slug: string;
+        readonly document: import("./document.js").Document;
+        readonly collection: import("./collection.js").Collection;
+
+        // Typed meta from Zod schema
+        readonly meta: z.infer<TMeta>;
+
+        // Sections: each key maps to the return type of its extract function
+        readonly sections: {
+          readonly [K in keyof TSections]: TSections[K] extends SectionDefinition<
+            infer U
+          >
+            ? U
+            : never;
+        };
+
+        // Relationships: each key becomes an accessor object
+        readonly relationships: {
+          [K in keyof TRelationships]: TRelationships[K] extends HasManyDefinition<
+            infer TTarget
+          >
+            ? HasManyAccessor<TTarget>
+            : TRelationships[K] extends BelongsToDefinition<infer TTarget>
+              ? BelongsToAccessor<TTarget>
+              : never;
+        };
+
+        // Computed: each key maps to the return type of the computed function
+        readonly computed: {
+          readonly [K in keyof TComputed]: TComputed[K] extends (
+            self: any,
+          ) => infer R
+            ? R
+            : never;
+        };
+
+        // Validation
+        validate(): Promise<ValidationResult>;
+        readonly errors: Map<string, import("zod").ZodIssue>;
+        readonly hasErrors: boolean;
+
+        // Serialization
+        toJSON(options?: SerializeOptions): Record<string, unknown>;
+
+        // Actions
+        runAction(
+          name: string,
+          options?: Record<string, unknown>,
+        ): Promise<unknown>;
+
+        // Persistence
+        save(options?: SaveOptions): Promise<void>;
+      }
+    : never;
+
+export interface HasManyAccessor<
+  TTarget extends ModelDefinition<any, any, any, any, any>,
+> {
+  fetchAll(): InferModelInstance<TTarget>[];
+  first(): InferModelInstance<TTarget> | undefined;
+  last(): InferModelInstance<TTarget> | undefined;
+  create(): Promise<InferModelInstance<TTarget>[]>;
+}
+
+export interface BelongsToAccessor<
+  TTarget extends ModelDefinition<any, any, any, any, any>,
+> {
+  fetch(): InferModelInstance<TTarget>;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: import("zod").ZodIssue[];
+}
+
+export interface SerializeOptions {
+  related?: string[];
+  sections?: string[];
+  computed?: string[];
+}
+
+export interface SaveOptions {
+  normalize?: boolean;
+  extension?: string;
+}
+
+/** Factory function type used to break circular dependency between model-instance and relationships */
+export type ModelInstanceFactory = (
+  doc: import("./document.js").Document,
+  definition: ModelDefinition<any, any, any, any, any>,
+  collection: import("./collection.js").Collection,
+) => any;

package/src/utils/index.ts

@@ -0,0 +1,11 @@
+export {
+  pluralize,
+  singularize,
+  kebabCase,
+  camelCase,
+  upperFirst,
+} from "./inflect";
+export { stringifyAst } from "./stringify-ast";
+export { parseTable } from "./parse-table";
+export { normalizeHeadings } from "./normalize-headings";
+export { readDirectory } from "./read-directory";

package/src/utils/inflect.ts

@@ -0,0 +1,82 @@
+const IRREGULAR: Record<string, string> = {
+  person: "people",
+  child: "children",
+  man: "men",
+  woman: "women",
+  mouse: "mice",
+  goose: "geese",
+  ox: "oxen",
+  datum: "data",
+  index: "indices",
+  matrix: "matrices",
+  vertex: "vertices",
+};
+
+const UNCOUNTABLE = new Set([
+  "sheep",
+  "fish",
+  "deer",
+  "series",
+  "species",
+  "money",
+  "rice",
+  "information",
+  "equipment",
+  "media",
+  "data",
+]);
+
+export function pluralize(word: string): string {
+  const lower = word.toLowerCase();
+
+  if (UNCOUNTABLE.has(lower)) return word;
+  if (IRREGULAR[lower]) {
+    return word[0] + IRREGULAR[lower].slice(1);
+  }
+
+  if (/s$/i.test(word)) return word;
+  if (/([^aeiou])y$/i.test(word)) return word.replace(/y$/i, "ies");
+  if (/(x|ch|ss|sh)$/i.test(word)) return word + "es";
+
+  return word + "s";
+}
+
+export function singularize(word: string): string {
+  const lower = word.toLowerCase();
+
+  if (UNCOUNTABLE.has(lower)) return word;
+
+  const irregularEntry = Object.entries(IRREGULAR).find(
+    ([, v]) => v === lower
+  );
+  if (irregularEntry) {
+    return word[0] + irregularEntry[0].slice(1);
+  }
+
+  if (word.endsWith("ies")) return word.slice(0, -3) + "y";
+  if (/ses$/i.test(word) || /xes$/i.test(word) || /ches$/i.test(word) || /shes$/i.test(word)) {
+    return word.slice(0, -2);
+  }
+  if (word.endsWith("s") && !word.endsWith("ss")) {
+    return word.slice(0, -1);
+  }
+  return word;
+}
+
+export function kebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^\w-]/g, "")
+    .toLowerCase();
+}
+
+export function camelCase(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+    .replace(/^[A-Z]/, (c) => c.toLowerCase());
+}
+
+export function upperFirst(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}