gray-matter-es 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,8 @@
 # gray-matter-es
 
+[![npm version](https://img.shields.io/npm/v/gray-matter-es?color=yellow)](https://npmjs.com/package/gray-matter-es)
+[![npm downloads](https://img.shields.io/npm/dm/gray-matter-es?color=yellow)](https://npmjs.com/package/gray-matter-es)
+
 ESM-only [gray-matter](https://github.com/jonschlinkert/gray-matter) implementation.
 
 ## Features
@@ -21,6 +24,8 @@ pnpm add gray-matter-es
 
 ```typescript
 import matter from "gray-matter-es";
+// or
+import { matter } from "gray-matter-es";
 
 // Parse front matter
 const file = matter("---\ntitle: Hello\n---\nThis is content");
@@ -124,6 +129,71 @@ Detect the language specified after the opening delimiter.
 - Removed `section-matter` support
 - TypeScript-first with strict types
 
+## Migration from gray-matter
+
+### Import Changes
+
+```diff
+- const matter = require('gray-matter');
++ import matter from 'gray-matter-es';
++ // or
++ import { matter } from 'gray-matter-es';
+```
+
+### Removed Features
+
+#### JavaScript Front Matter Engine
+
+The JavaScript engine has been removed for security reasons (it used `eval`). If you were using JavaScript front matter:
+
+```markdown
+---js
+{
+  title: "Hello",
+  date: new Date()
+}
+---
+```
+
+You'll need to either:
+
+1. Convert to YAML or JSON front matter
+2. Register a custom engine with your own parser
+
+#### Deprecated Options
+
+The following deprecated options have been removed:
+
+| Removed Option | Replacement  |
+| -------------- | ------------ |
+| `lang`         | `language`   |
+| `delims`       | `delimiters` |
+| `parsers`      | `engines`    |
+
+```diff
+- matter(str, { lang: 'json', delims: '~~~' });
++ matter(str, { language: 'json', delimiters: '~~~' });
+```
+
+#### Section Matter
+
+If you were using `section-matter` functionality, you'll need to handle it separately.
+
+### YAML Parser Differences
+
+This library uses `@std/yaml` instead of `js-yaml`. In most cases, this is a drop-in replacement, but there may be edge cases with non-standard YAML.
+
+### CommonJS Users
+
+If you're using CommonJS, you'll need to either:
+
+1. Migrate to ESM
+2. Use dynamic import:
+
+```javascript
+const matter = await import("gray-matter-es").then((m) => m.default);
+```
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,12 +1,96 @@
-import { Engine, GrayMatterFile, GrayMatterInput, GrayMatterOptions, MatterFunction, ResolvedOptions } from "./types.mjs";
-import { BuiltinLanguage } from "./engines.mjs";
-
+//#region src/types.d.ts
+/**
+* Engine interface for parsing and stringifying front matter
+*/
+interface Engine {
+  parse: (str: string) => Record<string, unknown>;
+  stringify?: (data: Record<string, unknown>) => string;
+}
+/**
+* Options for gray-matter
+*/
+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
+*/
+interface ResolvedOptions extends GrayMatterOptions {
+  delimiters: [string, string];
+  language: "yaml" | "json";
+}
+/**
+* The file object returned by gray-matter
+*/
+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
+*/
+type GrayMatterInput = string | Buffer | {
+  content: string;
+  data?: Record<string, unknown>;
+};
+/**
+* The matter function interface with static methods
+*/
+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>;
+}
+//#endregion
+//#region src/engines.d.ts
+/**
+* Built-in language names
+*/
+type BuiltinLanguage = "yaml" | "json";
+//#endregion
 //#region src/index.d.ts
-
 /**
 * The matter function with all static methods
 */
 declare const matter: MatterFunction;
 //#endregion
-export { type BuiltinLanguage, type Engine, type GrayMatterFile, type GrayMatterInput, type GrayMatterOptions, type MatterFunction, type ResolvedOptions, matter as default };
-//# sourceMappingURL=index.d.mts.map
+export { type BuiltinLanguage, type Engine, type GrayMatterFile, type GrayMatterInput, type GrayMatterOptions, type MatterFunction, type ResolvedOptions, matter as default, matter };