@jxsuite/parser 0.26.2 → 0.28.0

package/src/csv.ts

@@ -0,0 +1,209 @@
+/**
+ * Csv — CSV content format for Jx
+ *
+ * RFC 4180-style CSV parsing with schema-driven type coercion, packaged as a Jx
+ * format-extension class. `parse` is pure and browser-safe; `discover`, `load`, and
+ * instance `resolve` touch the filesystem (or fetch remote URLs) and dynamically
+ * import node modules so the module itself stays importable in the browser.
+ *
+ * @module @jxsuite/parser/csv
+ * @license MIT
+ */
+
+import type { ContentTypeSchema } from "@jxsuite/schema/types";
+import type { ContentLoaderEntry } from "./types.ts";
+
+// ─── CSV parser (minimal, spec-compliant) ────────────────────────────────────
+
+/**
+ * Parse a CSV string into an array of objects using the first row as headers. Handles quoted fields
+ * with commas and newlines.
+ */
+export function parseCSV(csv: string): Record<string, string>[] {
+  const rows: Record<string, string>[] = [];
+  let current = "";
+  let inQuotes = false;
+  const lines: string[] = [];
+
+  // Split into rows respecting quoted newlines (preserve raw characters)
+  for (let i = 0; i < csv.length; i++) {
+    const ch = csv[i];
+    if (ch === '"') {
+      current += ch;
+      if (inQuotes && csv[i + 1] === '"') {
+        current += csv[i + 1];
+        i++;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if ((ch === "\n" || (ch === "\r" && csv[i + 1] === "\n")) && !inQuotes) {
+      lines.push(current);
+      current = "";
+      if (ch === "\r") i++;
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) lines.push(current);
+
+  if (lines.length === 0) return [];
+
+  const parseRow = (line: string) => {
+    const fields: string[] = [];
+    let field = "";
+    let q = false;
+    for (let i = 0; i < line.length; i++) {
+      const ch = line[i];
+      if (ch === '"') {
+        if (q && line[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          q = !q;
+        }
+      } else if (ch === "," && !q) {
+        fields.push(field);
+        field = "";
+      } else {
+        field += ch;
+      }
+    }
+    fields.push(field);
+    return fields;
+  };
+
+  const headers = parseRow(lines[0]);
+  for (let i = 1; i < lines.length; i++) {
+    const fields = parseRow(lines[i]);
+    const obj: Record<string, string> = {};
+    for (let j = 0; j < headers.length; j++) {
+      obj[headers[j].trim()] = fields[j]?.trim() ?? "";
+    }
+    rows.push(obj);
+  }
+  return rows;
+}
+
+// ─── Type coercion ───────────────────────────────────────────────────────────
+
+export interface CsvOptions {
+  /** Content type schema — drives per-column type coercion. */
+  schema?: ContentTypeSchema;
+  /** Column used as entry id. Default fallback chain: id → sku → slug → Slug → row index. */
+  idField?: string;
+}
+
+/**
+ * Coerce raw CSV row strings to typed values per the schema. - number: strips currency
+ * symbols/commas; null for empty cells - boolean: "true" → true, everything else → false - array:
+ * comma-split, trimmed, empties dropped
+ */
+export function coerceCSVRows(
+  rows: Record<string, string>[],
+  schema?: ContentTypeSchema,
+  idField?: string,
+): ContentLoaderEntry[] {
+  return rows.map((row, i) => {
+    const data: Record<string, unknown> = { ...row };
+    if (schema?.properties) {
+      for (const [key, def] of Object.entries(schema.properties)) {
+        if (!(key in data)) continue;
+        if (def.type === "number") {
+          const raw = String(data[key] ?? "").trim();
+          if (raw === "") {
+            data[key] = null;
+          } else {
+            const cleaned = raw.replace(/[$€£¥,\s]/g, "");
+            const n = Number(cleaned);
+            data[key] = isNaN(n) ? null : n;
+          }
+        } else if (def.type === "boolean") {
+          data[key] = data[key] === "true";
+        } else if (def.type === "array") {
+          const raw = String(data[key] ?? "").trim();
+          data[key] =
+            raw === ""
+              ? []
+              : raw
+                  .split(",")
+                  .map((s) => s.trim())
+                  .filter(Boolean);
+        }
+      }
+    }
+    const id =
+      (idField ? (data[idField] as string | undefined) : undefined) ??
+      (data.id as string | undefined) ??
+      (data.sku as string | undefined) ??
+      (data.slug as string | undefined) ??
+      (data.Slug as string | undefined) ??
+      String(i);
+    return { id, data, body: null };
+  });
+}
+
+// ─── Csv format class ────────────────────────────────────────────────────────
+
+/**
+ * CSV format-extension class. Satisfies the Jx external class contract ($prototype + instance
+ * resolve) and the format capability contract (static parse / discover / load).
+ *
+ * @example
+ *   { "$prototype": "Csv", "$src": "@jxsuite/parser/Csv.class.json", "src": "./products.csv" }
+ */
+export class Csv {
+  config: { src: string; basePath?: string } & CsvOptions;
+
+  constructor(config: { src: string; basePath?: string } & CsvOptions) {
+    this.config = config;
+  }
+
+  /** Parse CSV source text into content entries (pure, browser-safe). */
+  static parse(source: string, options: CsvOptions = {}): ContentLoaderEntry[] {
+    return coerceCSVRows(parseCSV(source), options.schema, options.idField);
+  }
+
+  /** List .csv entry files for a content-type source (file path or directory). */
+  static async discover(source: string, options: { baseDir?: string } = {}): Promise<string[]> {
+    const { existsSync, readdirSync } = await import("node:fs");
+    const { resolve, extname } = await import("node:path");
+    const resolved = options.baseDir ? resolve(options.baseDir, source) : resolve(source);
+
+    if (extname(resolved)) {
+      return existsSync(resolved) ? [resolved] : [];
+    }
+    try {
+      return readdirSync(resolved, { recursive: true })
+        .filter((f) => String(f).endsWith(".csv"))
+        .map((f) => resolve(resolved, String(f)));
+    } catch {
+      return [];
+    }
+  }
+
+  /** Load one CSV source (file path or http(s) URL) into content entries. */
+  static async load(path: string, options: CsvOptions = {}): Promise<ContentLoaderEntry[]> {
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+      const response = await fetch(path);
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch CSV from ${path}: ${response.status} ${response.statusText}`,
+        );
+      }
+      return Csv.parse(await response.text(), options);
+    }
+    const { readFileSync } = await import("node:fs");
+    return Csv.parse(readFileSync(path, "utf-8"), options);
+  }
+
+  /** Runtime on-demand access: load the configured source. */
+  async resolve(): Promise<ContentLoaderEntry[]> {
+    const { src, basePath, ...options } = this.config;
+    if (src.startsWith("http://") || src.startsWith("https://")) {
+      return Csv.load(src, options);
+    }
+    const { resolve } = await import("node:path");
+    const filePath = basePath ? resolve(basePath, src) : resolve(src);
+    return Csv.load(filePath, options);
+  }
+}

package/src/markdown.ts

@@ -0,0 +1,112 @@
+/**
+ * Markdown — the markdown format-extension class for Jx
+ *
+ * Single class carrying every format capability:
+ * - static `parse` (markdown source → Jx document) — browser-safe
+ * - static `serialize` (Jx document → markdown source) — browser-safe
+ * - static `discover` / `load` (compile-time content access) — node-only, dynamic imports
+ * - instance `resolve` (runtime on-demand access for `$prototype: "Markdown"` state)
+ *
+ * The node-only capabilities dynamically import `node:fs` / `./md.ts` inside the
+ * method so this module stays importable in the browser (studio calls parse/serialize
+ * in-process).
+ *
+ * @module @jxsuite/parser/markdown
+ * @license MIT
+ */
+
+import { transpileJxMarkdown } from "./transpile.ts";
+import { serializeJxMarkdown, type SerializeOptions } from "./serialize.ts";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { ContentLoaderEntry, MarkdownFileResult } from "./types.ts";
+
+export interface MarkdownLoadOptions {
+  /** Options for the MarkdownDirective plugin (allowedNames, prefix, ...). */
+  directiveOptions?: unknown;
+  /** Enable remark-directive parsing. Implied by directiveOptions. */
+  directives?: boolean;
+}
+
+/**
+ * Markdown format class. Satisfies the Jx external class contract ($prototype + instance resolve)
+ * and the format capability contract (static parse / serialize / discover / load).
+ *
+ * @example
+ *   { "$prototype": "Markdown", "$src": "@jxsuite/parser/Markdown.class.json", "src": "./post.md" }
+ */
+export class Markdown {
+  config: { src: string; basePath?: string } & MarkdownLoadOptions;
+
+  constructor(config: { src: string; basePath?: string } & MarkdownLoadOptions) {
+    this.config = config;
+  }
+
+  /** Transpile Jx Markdown source into a complete Jx JSON document (browser-safe). */
+  static parse(source: string): JxDocument {
+    return transpileJxMarkdown(source);
+  }
+
+  /** Serialize a Jx document to markdown source (browser-safe). See SerializeOptions. */
+  static serialize(doc: JxDocument, options?: SerializeOptions): string {
+    return serializeJxMarkdown(doc, options);
+  }
+
+  /** List .md entry files for a content-type source (file path or directory). */
+  static async discover(source: string, options: { baseDir?: string } = {}): Promise<string[]> {
+    const { existsSync, readdirSync } = await import("node:fs");
+    const { resolve, extname } = await import("node:path");
+    const resolved = options.baseDir ? resolve(options.baseDir, source) : resolve(source);
+
+    if (extname(resolved)) {
+      return existsSync(resolved) ? [resolved] : [];
+    }
+    try {
+      return readdirSync(resolved, { recursive: true })
+        .filter((f) => String(f).endsWith(".md"))
+        .map((f) => resolve(resolved, String(f)));
+    } catch {
+      return [];
+    }
+  }
+
+  /** Load one markdown file into a content entry (frontmatter → data, body preserved). */
+  static async load(
+    path: string,
+    options: MarkdownLoadOptions = {},
+  ): Promise<ContentLoaderEntry[]> {
+    const { processMarkdown } = await import("./md.ts");
+    const { readFileSync } = await import("node:fs");
+    const source = readFileSync(path, "utf-8");
+    const result = processMarkdown(source, path, {
+      ...(options.directives !== undefined && { directives: options.directives }),
+      ...(options.directiveOptions !== undefined && {
+        directiveOptions: options.directiveOptions,
+      }),
+    });
+    const _meta: ContentLoaderEntry["_meta"] = {};
+    if (result.$excerpt != null) _meta.excerpt = result.$excerpt;
+    if (result.$toc != null) _meta.toc = result.$toc;
+    if (result.$readingTime != null) _meta.readingTime = result.$readingTime;
+    if (result.$wordCount != null) _meta.wordCount = result.$wordCount;
+    return [
+      {
+        id: result.slug,
+        data: result.frontmatter,
+        body: source,
+        $children: result.$children,
+        _meta,
+      },
+    ];
+  }
+
+  /** Runtime on-demand access: parse the configured markdown file. */
+  async resolve(): Promise<MarkdownFileResult> {
+    const { processMarkdown } = await import("./md.ts");
+    const { readFileSync } = await import("node:fs");
+    const { resolve } = await import("node:path");
+    const { src, basePath, ...processorConfig } = this.config;
+    const filePath = basePath ? resolve(basePath, src) : resolve(src);
+    const source = readFileSync(filePath, "utf-8");
+    return processMarkdown(source, filePath, processorConfig);
+  }
+}

package/src/md.ts

@@ -127,7 +127,7 @@ function extractExcerpt(tree: MdastNode) {
  * @param {unknown} [config.directiveOptions] - Directive plugin options
  * @returns {MarkdownFileResult}
  */
-function processMarkdown(
+export function processMarkdown(
   source: string,
   filePath: string,
   config: {
@@ -162,7 +162,7 @@ function processMarkdown(
     (n: MdastNode) => n.type !== "yaml" && n.type !== "toml",
   ) as MdastNode[];
   const $children = bodyNodes
-    .map(/** @type {(n: MdastNode) => any} */ (mdastNodeToJx))
+    .map(/** @type {(n: MdastNode) => any} */ mdastNodeToJx)
     .filter(Boolean) as (JxElement | string)[];
 
   return {
@@ -189,56 +189,13 @@ function getNestedValue(obj: Record<string, unknown> | MarkdownFileResult, path:
     .split(".")
     .reduce(
       (o: unknown, k) => (o as Record<string, unknown> | undefined)?.[k],
-      /** @type {unknown} */ (obj),
+      /** @type {unknown} */ obj,
     );
 }
 
-// ─── MarkdownFile ─────────────────────────────────────────────────────────────
+// ─── Markdown format class (re-exported from browser-safe module) ────────────
 
-/**
- * Parse a single markdown file. Satisfies the Jx external class contract ($prototype).
- *
- * @example
- *   { "$prototype": "MarkdownFile", "$src": "@jxsuite/md", "src": "./content/about.md" }
- */
-export class MarkdownFile {
-  config: {
-    src: string;
-    remarkPlugins?: unknown[];
-    rehypePlugins?: unknown[];
-    basePath?: string;
-    directives?: boolean;
-  };
-  /**
-   * @param {object} config
-   * @param {string} config.src - File path to markdown file
-   * @param {unknown[]} [config.remarkPlugins] Default is `[]`
-   * @param {unknown[]} [config.rehypePlugins] Default is `[]`
-   * @param {string} [config.basePath] - Base path for resolving src
-   * @param {boolean} [config.directives] - Enable directive support
-   */
-  constructor(config: {
-    src: string;
-    remarkPlugins?: unknown[];
-    rehypePlugins?: unknown[];
-    basePath?: string;
-    directives?: boolean;
-  }) {
-    this.config = config;
-  }
-
-  /**
-   * Parse and resolve the markdown file.
-   *
-   * @returns {MarkdownFileResult}
-   */
-  resolve() {
-    const { src, basePath, ...processorConfig } = this.config;
-    const filePath = basePath ? resolvePath(basePath, src) : resolvePath(src);
-    const source = readFileSync(filePath, "utf-8");
-    return processMarkdown(source, filePath, processorConfig);
-  }
-}
+export { Markdown } from "./markdown.ts";
 
 // ─── MarkdownCollection ───────────────────────────────────────────────────────
 
@@ -316,7 +273,7 @@ export class MarkdownCollection {
     // Filter
     let filtered = results;
     if (typeof filter === "function") {
-      filtered = results.filter(/** @type {(r: MarkdownFileResult) => boolean} */ (filter));
+      filtered = results.filter(/** @type {(r: MarkdownFileResult) => boolean} */ filter);
     }
 
     // Sort