gray-matter-es 0.0.0

package/src/to-file.ts

@@ -0,0 +1,178 @@
+import type { GrayMatterFile, GrayMatterInput, GrayMatterOptions } from "./types.ts";
+import { getStringProp, isObject, toBuffer, toString } from "./utils.ts";
+import { stringify } from "./stringify.ts";
+
+/**
+ * Internal input shape after normalization
+ */
+interface NormalizedInput {
+  content: string | Buffer;
+  data?: unknown;
+  language?: string;
+  matter?: string;
+}
+
+/**
+ * Normalize input to a consistent shape
+ */
+function normalizeInput(input: GrayMatterInput): NormalizedInput {
+  if (isObject(input)) {
+    return {
+      content: getStringProp(input, "content"),
+      data: input.data,
+      language: getStringProp(input, "language"),
+      matter: getStringProp(input, "matter"),
+    };
+  }
+  // string or Buffer
+  return { content: input };
+}
+
+/**
+ * Normalize the given value to ensure an object is returned
+ * with the expected properties.
+ */
+export function toFile(input: GrayMatterInput): GrayMatterFile {
+  const normalized = normalizeInput(input);
+  const data = isObject(normalized.data) ? normalized.data : {};
+  const content = toString(normalized.content ?? "");
+  const language = normalized.language ?? "";
+  const matter = normalized.matter ?? "";
+  const orig = toBuffer(normalized.content ?? "");
+
+  const file: GrayMatterFile = {
+    data,
+    content,
+    excerpt: "",
+    orig,
+    language,
+    matter,
+    isEmpty: false,
+    stringify(
+      this: GrayMatterFile,
+      newData?: Record<string, unknown>,
+      options?: GrayMatterOptions,
+    ) {
+      if (options?.language) {
+        this.language = options.language;
+      }
+      return stringify(this, newData, options);
+    },
+  };
+
+  return file;
+}
+
+if (import.meta.vitest) {
+  const { fc, test } = await import("@fast-check/vitest");
+  const { Buffer } = await import("node:buffer");
+
+  describe("toFile", () => {
+    it("should convert string to file object", () => {
+      const result = toFile("hello world");
+      expect(result.content).toBe("hello world");
+      expect(result.data).toEqual({});
+      expect(result.isEmpty).toBe(false);
+      expect(result.excerpt).toBe("");
+      expect(result.language).toBe("");
+      expect(result.matter).toBe("");
+    });
+
+    it("should convert Buffer to file object", () => {
+      const result = toFile(Buffer.from("buffer content"));
+      expect(result.content).toBe("buffer content");
+      expect(result.data).toEqual({});
+    });
+
+    it("should handle object with content property", () => {
+      const result = toFile({ content: "object content", data: { key: "value" } });
+      expect(result.content).toBe("object content");
+      expect(result.data).toEqual({ key: "value" });
+    });
+
+    it("should preserve orig as Buffer", () => {
+      const result = toFile("test");
+      expect(Buffer.isBuffer(result.orig)).toBe(true);
+      expect(result.orig.toString()).toBe("test");
+    });
+
+    it("should set stringify as a function", () => {
+      const result = toFile("content");
+      expect(typeof result.stringify).toBe("function");
+    });
+
+    it("should initialize data to empty object if not provided", () => {
+      const result = toFile({ content: "test" });
+      expect(result.data).toEqual({});
+    });
+
+    it("should strip BOM from content", () => {
+      const bomString = "\uFEFFhello";
+      const result = toFile(bomString);
+      expect(result.content).toBe("hello");
+    });
+
+    it("should preserve existing language", () => {
+      const result = toFile({ content: "test", language: "json" } as GrayMatterInput);
+      expect(result.language).toBe("json");
+    });
+
+    it("should preserve existing matter", () => {
+      const result = toFile({ content: "test", matter: "raw matter" } as GrayMatterInput);
+      expect(result.matter).toBe("raw matter");
+    });
+
+    test.prop([fc.string({ minLength: 0, maxLength: 200 })])(
+      "should always return valid file object for any string",
+      (input) => {
+        const result = toFile(input);
+        expect(typeof result.content).toBe("string");
+        expect(typeof result.data).toBe("object");
+        expect(result.data).not.toBeNull();
+        expect(typeof result.isEmpty).toBe("boolean");
+        expect(typeof result.excerpt).toBe("string");
+        expect(typeof result.language).toBe("string");
+        expect(typeof result.matter).toBe("string");
+        expect(Buffer.isBuffer(result.orig)).toBe(true);
+        expect(typeof result.stringify).toBe("function");
+      },
+    );
+
+    test.prop([fc.uint8Array({ minLength: 0, maxLength: 200 })])(
+      "should handle any Buffer input",
+      (arr) => {
+        const buffer = Buffer.from(arr);
+        const result = toFile(buffer);
+        expect(typeof result.content).toBe("string");
+        expect(Buffer.isBuffer(result.orig)).toBe(true);
+      },
+    );
+
+    test.prop([
+      fc.record({
+        content: fc.string({ minLength: 0, maxLength: 100 }),
+        data: fc.option(fc.dictionary(fc.string(), fc.string(), { maxKeys: 5 }), {
+          nil: undefined,
+        }),
+      }),
+    ])("should handle object input with optional data", ({ content, data }) => {
+      const input = data !== undefined ? { content, data } : { content };
+      const result = toFile(input);
+      expect(result.content).toBe(content);
+      expect(typeof result.data).toBe("object");
+      if (data !== undefined) {
+        expect(result.data).toEqual(data);
+      }
+    });
+
+    test.prop([fc.string({ minLength: 1, maxLength: 50 })])(
+      "should strip BOM consistently",
+      (str) => {
+        const withBom = "\uFEFF" + str;
+        const result = toFile(withBom);
+        expect(result.content).toBe(str);
+        expect(result.content.charCodeAt(0)).not.toBe(0xfeff);
+      },
+    );
+  });
+}

package/src/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Engine interface for parsing and stringifying front matter
+ */
+export interface Engine {
+  parse: (str: string) => Record<string, unknown>;
+  stringify?: (data: Record<string, unknown>) => string;
+}
+
+/**
+ * Options for gray-matter
+ */
+export interface GrayMatterOptions {
+  /** Language to use for parsing (default: 'yaml') */
+  language?: "yaml" | "json";
+  /** Delimiters for front matter (default: '---') */
+  delimiters?: string | [string, string];
+  /**
+   * Extract an excerpt from the content.
+   * - `true`: use the default delimiter
+   * - `string`: use this string as the delimiter
+   * - `function`: custom excerpt function
+   */
+  excerpt?: boolean | string | ((file: GrayMatterFile, options: GrayMatterOptions) => void);
+  /** Separator for excerpt in file.data */
+  excerpt_separator?: string;
+  /** Data to merge with parsed data */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Resolved options with defaults applied
+ */
+export interface ResolvedOptions extends GrayMatterOptions {
+  delimiters: [string, string];
+  language: "yaml" | "json";
+}
+
+/**
+ * The file object returned by gray-matter
+ */
+export interface GrayMatterFile {
+  /** The parsed front matter data */
+  data: Record<string, unknown>;
+  /** The content after front matter */
+  content: string;
+  /** The extracted excerpt (if enabled) */
+  excerpt: string;
+  /** The original input as a Buffer */
+  orig: Buffer;
+  /** The detected/specified language */
+  language: string;
+  /** The raw front matter string (without delimiters) */
+  matter: string;
+  /** True if front matter block was empty */
+  isEmpty: boolean;
+  /** The original content if isEmpty is true */
+  empty?: string;
+  /** File path (set by matter.read) */
+  path?: string;
+  /** Stringify the file back to a string */
+  stringify: (data?: Record<string, unknown>, options?: GrayMatterOptions) => string;
+}
+
+/**
+ * Input that can be passed to gray-matter
+ */
+export type GrayMatterInput = string | Buffer | { content: string; data?: Record<string, unknown> };
+
+/**
+ * The matter function interface with static methods
+ */
+export interface MatterFunction {
+  (input: GrayMatterInput, options?: GrayMatterOptions): GrayMatterFile;
+  stringify: (
+    file: GrayMatterFile | string,
+    data?: Record<string, unknown>,
+    options?: GrayMatterOptions,
+  ) => string;
+  read: (filepath: string, options?: GrayMatterOptions) => GrayMatterFile;
+  test: (str: string, options?: GrayMatterOptions) => boolean;
+  language: (str: string, options?: GrayMatterOptions) => { raw: string; name: string };
+  clearCache: () => void;
+  cache: Map<string, GrayMatterFile>;
+}

package/src/utils.ts

@@ -0,0 +1,158 @@
+import { Buffer } from "node:buffer";
+
+/**
+ * Strip BOM (Byte Order Mark) from a string
+ */
+function stripBom(str: string): string {
+  return str.charCodeAt(0) === 0xfeff ? str.slice(1) : str;
+}
+
+/**
+ * Returns true if `val` is a Buffer
+ */
+function isBuffer(val: unknown): val is Buffer {
+  return Buffer.isBuffer(val);
+}
+
+/**
+ * Returns true if `val` is a plain object (not a Buffer or other special object)
+ */
+export function isObject(val: unknown): val is Record<string, unknown> {
+  return typeof val === "object" && val !== null && !Array.isArray(val) && !Buffer.isBuffer(val);
+}
+
+/**
+ * Cast `input` to a Buffer
+ */
+export function toBuffer(input: string | Buffer): Buffer {
+  return typeof input === "string" ? Buffer.from(input) : input;
+}
+
+/**
+ * Cast `input` to a string, stripping BOM
+ */
+export function toString(input: string | Buffer): string {
+  if (isBuffer(input)) return stripBom(String(input));
+  if (typeof input !== "string") {
+    throw new TypeError("expected input to be a string or buffer");
+  }
+  return stripBom(input);
+}
+
+/**
+ * Cast `val` to an array
+ */
+export function arrayify<T>(val: T | T[] | undefined | null): T[] {
+  return val ? (Array.isArray(val) ? val : [val]) : [];
+}
+
+/**
+ * Asserts that `val` is a plain object and returns it typed as Record<string, unknown>
+ * If `val` is not a plain object, returns an empty object
+ */
+export function toRecord(val: unknown): Record<string, unknown> {
+  return isObject(val) ? val : {};
+}
+
+/**
+ * Get a string property from an object with a default value
+ */
+export function getStringProp(obj: unknown, key: string, defaultValue = ""): string {
+  if (!isObject(obj)) return defaultValue;
+  const value = obj[key];
+  return typeof value === "string" ? value : defaultValue;
+}
+
+if (import.meta.vitest) {
+  describe("utils", () => {
+    describe("toRecord", () => {
+      it("should return object as-is", () => {
+        const obj = { a: 1, b: "hello" };
+        expect(toRecord(obj)).toBe(obj);
+      });
+
+      it("should return empty object for non-objects", () => {
+        expect(toRecord(null)).toEqual({});
+        expect(toRecord(undefined)).toEqual({});
+        expect(toRecord("string")).toEqual({});
+        expect(toRecord(123)).toEqual({});
+        expect(toRecord([])).toEqual({});
+      });
+    });
+
+    describe("getStringProp", () => {
+      it("should return string property value", () => {
+        expect(getStringProp({ name: "test" }, "name")).toBe("test");
+      });
+
+      it("should return default for missing property", () => {
+        expect(getStringProp({ other: "value" }, "name")).toBe("");
+        expect(getStringProp({ other: "value" }, "name", "default")).toBe("default");
+      });
+
+      it("should return default for non-string property", () => {
+        expect(getStringProp({ count: 42 }, "count")).toBe("");
+        expect(getStringProp({ flag: true }, "flag")).toBe("");
+      });
+
+      it("should return default for non-objects", () => {
+        expect(getStringProp(null, "name")).toBe("");
+        expect(getStringProp("string", "name")).toBe("");
+      });
+    });
+
+    describe("stripBom", () => {
+      it("should strip BOM from string", () => {
+        expect(stripBom("\uFEFFhello")).toBe("hello");
+      });
+
+      it("should return string unchanged if no BOM", () => {
+        expect(stripBom("hello")).toBe("hello");
+      });
+    });
+
+    describe("isBuffer", () => {
+      it("should return true for Buffer", () => {
+        expect(isBuffer(Buffer.from("test"))).toBe(true);
+      });
+
+      it("should return false for string", () => {
+        expect(isBuffer("test")).toBe(false);
+      });
+    });
+
+    describe("isObject", () => {
+      it("should return true for plain object", () => {
+        expect(isObject({})).toBe(true);
+        expect(isObject({ a: 1 })).toBe(true);
+      });
+
+      it("should return false for array", () => {
+        expect(isObject([])).toBe(false);
+      });
+
+      it("should return false for null", () => {
+        expect(isObject(null)).toBe(false);
+      });
+
+      it("should return false for Buffer", () => {
+        expect(isObject(Buffer.from("test"))).toBe(false);
+      });
+    });
+
+    describe("arrayify", () => {
+      it("should wrap non-array in array", () => {
+        expect(arrayify("test")).toEqual(["test"]);
+      });
+
+      it("should return array unchanged", () => {
+        expect(arrayify(["a", "b"])).toEqual(["a", "b"]);
+      });
+
+      it("should return empty array for null/undefined", () => {
+        expect(arrayify(null)).toEqual([]);
+        expect(arrayify(undefined)).toEqual([]);
+      });
+    });
+  });
+}