@jxsuite/parser 2.0.1 → 3.0.0

package/src/types.ts

@@ -1,4 +1,12 @@
-import type { JxElement, TocEntry } from "@jxsuite/schema/types";
+import type { Root } from "mdast";
+import type {
+  ContentFieldValue,
+  ContentTypeSchema,
+  JsonObject,
+  JsonValue,
+  JxElement,
+  TocEntry,
+} from "@jxsuite/schema/types";
 
 // The content wire types are core (extensions implement them, hosts thread them); re-exported here
 // So parser-internal modules and downstream consumers keep their historical import path.
@@ -7,16 +15,21 @@ export type { ContentLoaderEntry, TocEntry } from "@jxsuite/schema/types";
 export interface MarkdownFileResult {
   slug: string;
   path: string;
-  frontmatter: Record<string, unknown>;
+  /** The parsed front matter: the same field space a loaded content entry's `data` carries. */
+  frontmatter: Record<string, ContentFieldValue | undefined>;
   $children: (JxElement | string)[];
   $excerpt?: string;
   $toc?: TocEntry[];
   $readingTime?: number;
   $wordCount?: number;
-  [key: string]: unknown;
 }
 
-export type ContentEntry = MarkdownFileResult & Record<string, unknown>;
+/**
+ * A processed markdown file that may carry fields beyond the ones {@link MarkdownFileResult}
+ * declares: any value one of those members holds, or a front-matter field value.
+ */
+export type ContentEntry = MarkdownFileResult &
+  Record<string, MarkdownFileResult[keyof MarkdownFileResult] | ContentFieldValue>;
 
 /**
  * A content-type definition in the project.json `content` section — the parser extension owns this
@@ -25,12 +38,12 @@ export type ContentEntry = MarkdownFileResult & Record<string, unknown>;
 export interface ContentTypeDef {
   source?: string;
   format?: string;
-  schema?: Record<string, unknown>;
+  schema?: ContentTypeSchema;
   $elements?: (string | { $ref: string })[];
   /** Globs, relative to a directory `source`, for files that are never read. */
   exclude?: string[];
   /** Declarative frontmatter filter: only entries that satisfy it are kept. */
-  where?: Record<string, unknown>;
+  where?: JsonObject;
   /** Frontmatter field whose value is the entry id (the path-derived id when absent). */
   idField?: string;
   /** Route template giving each entry its URL. */
@@ -44,7 +57,8 @@ export interface ContentTypeDef {
    * blockquote. `false` for the whole option turns callouts off, `true` is the default.
    */
   alerts?: Record<string, string | boolean | null> | boolean;
-  [key: string]: unknown;
+  /** Format-specific options, read from `project.json` like every key above. */
+  [key: string]: JsonValue | ContentTypeSchema | undefined;
 }
 
 export interface MdastNode {
@@ -68,6 +82,13 @@ export interface MdastNode {
   align?: (string | null)[] | null;
 }
 
+/**
+ * A unified attacher: called by unified with `this` bound to the processor and the settings passed
+ * after it to `use`. Its result (a parser, compiler or transformer) is consumed by unified, never
+ * by the pipeline, and every plugin this package installs takes only JSON settings.
+ */
+export type UnifiedPlugin = (...settings: never[]) => void;
+
 /**
  * Minimal structural type for the unified() processor chain.
  *
@@ -77,16 +98,27 @@ export interface MdastNode {
  * boundary, so the rest of the pipeline is properly typed instead of `any`.
  */
 export interface UnifiedProcessor {
-  use: (plugin: unknown, ...options: unknown[]) => UnifiedProcessor;
+  use: (plugin: UnifiedPlugin, ...settings: JsonValue[]) => UnifiedProcessor;
   parse: (source: string) => MdastNode;
-  runSync: (tree: MdastNode, file?: unknown) => MdastNode;
-  stringify: (tree: unknown) => string;
+  runSync: (tree: MdastNode, file?: UnifiedFile) => MdastNode;
+  stringify: (tree: MdastNode | Root) => string;
+}
+
+/**
+ * The part of a VFile the pipeline hands to `runSync` and reads back. unified wraps the object in a
+ * VFile that shares this `data` record, and `remark-parse-frontmatter` stores the YAML block's
+ * parse there. `yaml.parse` uses the YAML 1.2 core schema (no timestamps), so the result is plain
+ * JSON; a document with no front matter, or an empty block, leaves it absent or `null`.
+ */
+export interface UnifiedFile {
+  data: { frontmatter?: JsonValue };
 }
 
 export interface HastNode {
   type: string;
   tagName?: string;
-  properties?: Record<string, unknown>;
+  /** Hast's property values (`hast` Properties). */
+  properties?: Record<string, string | number | boolean | (string | number)[] | null | undefined>;
   children?: HastNode[];
   value?: string;
 }