mdast-util-mdx-expression - npm Package Compare versions

Comparing version 1.3.1 to 1.3.2

complex-types.d.ts

@@ -1,40 +0,9 @@
-import type {Literal} from 'mdast'
-import type {Program} from 'estree-jsx'
+// To do: next major: remove this file.
+export type {
+  MdxFlowExpression,
+  MdxTextExpression,
+  MDXFlowExpression,
+  MDXTextExpression
+} from './index.js'
 
-/* eslint-disable @typescript-eslint/consistent-type-definitions */
-export interface MdxFlowExpression extends Literal {
-  type: 'mdxFlowExpression'
-  data?: {
-    estree?: Program
-  } & Literal['data']
-}
-
-export interface MdxTextExpression extends Literal {
-  type: 'mdxTextExpression'
-  data?: {
-    estree?: Program
-  } & Literal['data']
-}
-
-declare module 'mdast' {
-  interface StaticPhrasingContentMap {
-    mdxTextExpression: MdxTextExpression
-  }
-
-  interface BlockContentMap {
-    mdxFlowExpression: MdxFlowExpression
-  }
-}
-
-declare module 'hast' {
-  interface RootContentMap {
-    mdxTextExpression: MdxTextExpression
-    mdxFlowExpression: MdxFlowExpression
-  }
-
-  interface ElementContentMap {
-    mdxTextExpression: MdxTextExpression
-    mdxFlowExpression: MdxFlowExpression
-  }
-}
-/* eslint-enable @typescript-eslint/consistent-type-definitions */
+/// <reference types="./index.js" />

index.d.ts

@@ -0,26 +1,154 @@
+import type {Program} from 'estree-jsx'
+import type {Literal as HastLiteral} from 'hast'
+import type {Literal as MdastLiteral} from 'mdast'
+
+export {
+  mdxExpressionFromMarkdown,
+  mdxExpressionToMarkdown
+} from './lib/index.js'
+
 /**
- * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
- * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
- * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
- * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
- * @typedef {import('estree-jsx').Program} Program
- * @typedef {import('./complex-types.js').MdxFlowExpression} MdxFlowExpression
- * @typedef {import('./complex-types.js').MdxTextExpression} MdxTextExpression
+ * MDX expression node, occurring in flow (block).
  */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface MdxFlowExpression extends MdastLiteral {
+  /**
+   * Node type.
+   */
+  type: 'mdxFlowExpression'
+
+  /**
+   * Data.
+   */
+  data?: {
+    /**
+     * Program node from estree.
+     */
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    estree?: Program | null | undefined
+  } & MdastLiteral['data']
+}
+
 /**
- * @typedef {MdxFlowExpression} MDXFlowExpression
- * @typedef {MdxTextExpression} MDXTextExpression
+ * MDX expression node, occurring in text (phrasing).
  */
-/** @type {FromMarkdownExtension} */
-export const mdxExpressionFromMarkdown: FromMarkdownExtension
-/** @type {ToMarkdownExtension} */
-export const mdxExpressionToMarkdown: ToMarkdownExtension
-export type FromMarkdownExtension = import('mdast-util-from-markdown').Extension
-export type FromMarkdownHandle = import('mdast-util-from-markdown').Handle
-export type ToMarkdownExtension = import('mdast-util-to-markdown').Options
-export type ToMarkdownHandle = import('mdast-util-to-markdown').Handle
-export type Program = import('estree-jsx').Program
-export type MdxFlowExpression = import('./complex-types.js').MdxFlowExpression
-export type MdxTextExpression = import('./complex-types.js').MdxTextExpression
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface MdxTextExpression extends MdastLiteral {
+  /**
+   * Node type.
+   */
+  type: 'mdxTextExpression'
+
+  /**
+   * Data.
+   */
+  data?: {
+    /**
+     * Program node from estree.
+     */
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    estree?: Program | null | undefined
+  } & MdastLiteral['data']
+}
+
+/**
+ * Deprecated: use `MdxFlowExpression`.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
 export type MDXFlowExpression = MdxFlowExpression
+
+/**
+ * Deprecated: use `MdxTextExpression`.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
 export type MDXTextExpression = MdxTextExpression
+
+/**
+ * MDX expression node, occurring in flow (block), for hast.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface MdxFlowExpressionHast extends HastLiteral {
+  /**
+   * Node type.
+   */
+  type: 'mdxFlowExpression'
+
+  /**
+   * Data.
+   */
+  data?: {
+    /**
+     * Program node from estree.
+     */
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    estree?: Program | null | undefined
+  } & HastLiteral['data']
+}
+
+/**
+ * MDX expression node, occurring in text (phrasing), for hast.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface MdxTextExpressionHast extends HastLiteral {
+  /**
+   * Node type.
+   */
+  type: 'mdxTextExpression'
+
+  /**
+   * Data.
+   */
+  data?: {
+    /**
+     * Program node from estree.
+     */
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    estree?: Program | null | undefined
+  } & HastLiteral['data']
+}
+
+// Add nodes to mdast content.
+declare module 'mdast' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface StaticPhrasingContentMap {
+    /**
+     * MDX expression node, occurring in text (phrasing).
+     */
+    mdxTextExpression: MdxTextExpression
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface BlockContentMap {
+    /**
+     * MDX expression node, occurring in flow (block).
+     */
+    mdxFlowExpression: MdxFlowExpression
+  }
+}
+
+// Add nodes to hast content.
+declare module 'hast' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface RootContentMap {
+    /**
+     * MDX expression node, occurring in flow (block).
+     */
+    mdxFlowExpression: MdxFlowExpressionHast
+    /**
+     * MDX expression node, occurring in text (phrasing).
+     */
+    mdxTextExpression: MdxTextExpressionHast
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface ElementContentMap {
+    /**
+     * MDX expression node, occurring in flow (block).
+     */
+    mdxFlowExpression: MdxFlowExpressionHast
+    /**
+     * MDX expression node, occurring in text (phrasing).
+     */
+    mdxTextExpression: MdxTextExpressionHast
+  }
+}

index.js

@@ -1,83 +0,5 @@
-/**
- * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
- * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
- * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
- * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
- * @typedef {import('estree-jsx').Program} Program
- * @typedef {import('./complex-types.js').MdxFlowExpression} MdxFlowExpression
- * @typedef {import('./complex-types.js').MdxTextExpression} MdxTextExpression
- */
-
-/**
- * @typedef {MdxFlowExpression} MDXFlowExpression
- * @typedef {MdxTextExpression} MDXTextExpression
- */
-
-/** @type {FromMarkdownExtension} */
-export const mdxExpressionFromMarkdown = {
-  enter: {
-    mdxFlowExpression: enterMdxFlowExpression,
-    mdxTextExpression: enterMdxTextExpression
-  },
-  exit: {
-    mdxFlowExpression: exitMdxExpression,
-    mdxFlowExpressionChunk: exitMdxExpressionData,
-    mdxTextExpression: exitMdxExpression,
-    mdxTextExpressionChunk: exitMdxExpressionData
-  }
-}
-
-/** @type {ToMarkdownExtension} */
-export const mdxExpressionToMarkdown = {
-  handlers: {
-    mdxFlowExpression: handleMdxExpression,
-    mdxTextExpression: handleMdxExpression
-  },
-  unsafe: [
-    {character: '{', inConstruct: ['phrasing']},
-    {atBreak: true, character: '{'}
-  ]
-}
-
-/** @type {FromMarkdownHandle} */
-function enterMdxFlowExpression(token) {
-  this.enter({type: 'mdxFlowExpression', value: ''}, token)
-  this.buffer()
-}
-
-/** @type {FromMarkdownHandle} */
-function enterMdxTextExpression(token) {
-  this.enter({type: 'mdxTextExpression', value: ''}, token)
-  this.buffer()
-}
-
-/** @type {FromMarkdownHandle} */
-function exitMdxExpression(token) {
-  const value = this.resume()
-  /** @type {Program|undefined} */
-  // @ts-expect-error: estree.
-  const estree = token.estree
-  const node = /** @type {MDXFlowExpression|MDXTextExpression} */ (
-    this.exit(token)
-  )
-  node.value = value
-
-  if (estree) {
-    node.data = {estree}
-  }
-}
-
-/** @type {FromMarkdownHandle} */
-function exitMdxExpressionData(token) {
-  this.config.enter.data.call(this, token)
-  this.config.exit.data.call(this, token)
-}
-
-/**
- * @type {ToMarkdownHandle}
- * @param {MDXFlowExpression|MDXTextExpression} node
- */
-function handleMdxExpression(node) {
-  const value = node.value || ''
-  return '{' + value + '}'
-}
+// Note: types exposed from `index.d.ts`.
+export {
+  mdxExpressionFromMarkdown,
+  mdxExpressionToMarkdown
+} from './lib/index.js'

package.json

 {
   "name": "mdast-util-mdx-expression",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "mdast extension to parse and serialize MDX (or MDX.js) expressions",
@@ -34,2 +34,3 @@ "license": "MIT",
   "files": [
+    "lib/",
     "complex-types.d.ts",
@@ -48,3 +49,3 @@ "index.d.ts",
     "@types/acorn": "^4.0.0",
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "acorn": "^8.0.0",
@@ -56,14 +57,13 @@ "c8": "^7.0.0",
     "remark-preset-wooorm": "^9.0.0",
-    "rimraf": "^3.0.0",
-    "tape": "^5.0.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
     "unist-util-remove-position": "^4.0.0",
-    "xo": "^0.52.0"
+    "xo": "^0.53.0"
   },
   "scripts": {
-    "build": "rimraf \"{index,test}.d.ts\" && tsc && type-coverage",
+    "prepack": "npm run build && npm run format",
+    "build": "tsc --build --clean && tsc --build && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test.js",
-    "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --conditions development test.js",
+    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
     "test": "npm run build && npm run format && npm run test-coverage"
@@ -70,0 +70,0 @@ },

readme.md

@@ -11,3 +11,3 @@ # mdast-util-mdx-expression
 
-[mdast][] extensions to parse and serialize [MDX][] expressions.
+[mdast][] extensions to parse and serialize [MDX][] expressions (`{Math.PI}`).
 
@@ -23,2 +23,8 @@ ## Contents
     *   [`mdxExpressionToMarkdown`](#mdxexpressiontomarkdown)
+    *   [`MdxFlowExpression`](#mdxflowexpression)
+    *   [`MdxTextExpression`](#mdxtextexpression)
+    *   [`MdxFlowExpressionHast`](#mdxflowexpressionhast)
+    *   [`MdxTextExpressionHast`](#mdxtextexpressionhast)
+*   [HTML](#html)
+*   [Syntax](#syntax)
 *   [Syntax tree](#syntax-tree)
@@ -35,16 +41,24 @@ *   [Nodes](#nodes)
 
-This package contains extensions that add support for the expression syntax
-enabled by MDX to [`mdast-util-from-markdown`][mdast-util-from-markdown] and
-[`mdast-util-to-markdown`][mdast-util-to-markdown].
+This package contains two extensions that add support for MDX expression syntax
+in markdown to [mdast][].
+These extensions plug into
+[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
+expressions in markdown into a syntax tree) and
+[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
+expressions in syntax trees to markdown).
 
 ## When to use this
 
-These tools are all rather low-level.
-In most cases, you’d want to use [`remark-mdx`][remark-mdx] with remark instead.
+You can use these extensions when you are working with
+`mdast-util-from-markdown` and `mdast-util-to-markdown` already.
 
+When working with `mdast-util-from-markdown`, you must combine this package
+with [`micromark-extension-mdx-expression`][extension].
+
 When you are working with syntax trees and want all of MDX, use
 [`mdast-util-mdx`][mdast-util-mdx] instead.
 
-When working with `mdast-util-from-markdown`, you must combine this package with
-[`micromark-extension-mdx-expression`][extension].
+All these packages are used in [`remark-mdx`][remark-mdx], which
+focusses on making it easier to transform content by abstracting these
+internals away.
 
@@ -54,3 +68,3 @@ ## Install
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+In Node.js (version 14.14+ and 16.0+), install with [npm][]:
 
@@ -175,4 +189,5 @@ ```sh
 
-This package exports the identifiers `mdxExpressionFromMarkdown` and
-`mdxExpressionToMarkdown`.
+This package exports the identifiers
+[`mdxExpressionFromMarkdown`][api-mdx-expression-from-markdown] and
+[`mdxExpressionToMarkdown`][api-mdx-expression-to-markdown].
 There is no default export.
@@ -182,11 +197,91 @@
 
-Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown].
+Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown] to enable
+MDX expressions.
 
-When using the [syntax extension with `addResult`][extension], nodes will have
-a `data.estree` field set to an [ESTree][].
+When using the [micromark syntax extension][extension] with `addResult`, nodes
+will have a `data.estree` field set to an ESTree [`Program`][program] node.
 
 ### `mdxExpressionToMarkdown`
 
-Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown].
+Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to enable MDX
+expressions.
 
+### `MdxFlowExpression`
+
+MDX expression node, occurring in flow (block) (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'mdast'
+
+interface MdxFlowExpression extends Literal {
+  type: 'mdxFlowExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+### `MdxTextExpression`
+
+MDX expression node, occurring in text (block) (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'mdast'
+
+interface MdxTextExpression extends Literal {
+  type: 'mdxTextExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+### `MdxFlowExpressionHast`
+
+Same as [`MdxFlowExpression`][api-mdx-flow-expression], but registered with
+`@types/hast` (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'hast'
+
+interface MdxFlowExpressionHast extends Literal {
+  type: 'mdxFlowExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+### `MdxTextExpressionHast`
+
+Same as [`MdxTextExpression`][api-mdx-text-expression], but registered with
+`@types/hast` (TypeScript type).
+
+###### Type
+
+```ts
+import type {Program} from 'estree-jsx'
+import type {Literal} from 'hast'
+
+interface MdxTextExpressionHast extends Literal {
+  type: 'mdxTextExpression'
+  data?: {estree?: Program | null | undefined} & Literal['data']
+}
+```
+
+## HTML
+
+MDX expressions have no representation in HTML.
+Though, when you are dealing with MDX, you will likely go *through* hast.
+You can enable passing MDX expressions through to hast by configuring
+[`mdast-util-to-hast`][mdast-util-to-hast] with
+`passThrough: ['mdxFlowExpression', 'mdxTextExpression']`.
+
+## Syntax
+
+See [Syntax in `micromark-extension-mdx-expression`][syntax].
+
 ## Syntax tree
@@ -198,6 +293,6 @@
 
-#### `MDXFlowExpression`
+#### `MdxFlowExpression`
 
 ```idl
-interface MDXFlowExpression <: Literal {
+interface MdxFlowExpression <: Literal {
   type: "mdxFlowExpression"
@@ -207,3 +302,3 @@ }
 
-**MDXFlowExpression** (**[Literal][dfn-literal]**) represents a JavaScript
+**MdxFlowExpression** (**[Literal][dfn-literal]**) represents a JavaScript
 expression embedded in flow (block).
@@ -227,6 +322,6 @@ It can be used where **[flow][dfn-flow-content]** content is expected.
 
-#### `MDXTextExpression`
+#### `MdxTextExpression`
 
 ```idl
-interface MDXTextExpression <: Literal {
+interface MdxTextExpression <: Literal {
   type: "mdxTextExpression"
@@ -236,3 +331,3 @@ }
 
-**MDXTextExpression** (**[Literal][dfn-literal]**) represents a JavaScript
+**MdxTextExpression** (**[Literal][dfn-literal]**) represents a JavaScript
 expression embedded in text (span, inline).
@@ -259,3 +354,3 @@ It can be used where **[phrasing][dfn-phrasing-content]** content is expected.
 ```idl
-type FlowContentMdxExpression = MDXFlowExpression | FlowContent
+type FlowContentMdxExpression = MdxFlowExpression | FlowContent
 ```
@@ -266,3 +361,3 @@
 ```idl
-type PhrasingContentMdxExpression = MDXTextExpression | PhrasingContent
+type PhrasingContentMdxExpression = MdxTextExpression | PhrasingContent
 ```
@@ -273,5 +368,8 @@
 This package is fully typed with [TypeScript][].
-It exports the additional types `MdxFlowExpression` and `MdxTextExpression`.
+It exports the additional types [`MdxFlowExpression`][api-mdx-flow-expression],
+[`MdxFlowExpressionHast`][api-mdx-flow-expression-hast],
+[`MdxTextExpression`][api-mdx-text-expression], and
+[`MdxTextExpressionHast`][api-mdx-text-expression-hast].
 
-It also registers the node types with `@types/mdast`.
+It also registers the node types with `@types/mdast` and `@types/hast`.
 If you’re working with the syntax tree, make sure to import this utility
@@ -299,3 +397,3 @@ somewhere in your types, as that registers the new node types in the tree.
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+As of now, that is Node.js 14.14+ and 16.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
@@ -379,2 +477,4 @@
 
+[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
+
 [mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
@@ -388,12 +488,26 @@
 
-[estree]: https://github.com/estree/estree
+[syntax]: https://github.com/micromark/micromark-extension-mdx-expression#syntax
 
+[program]: https://github.com/estree/estree/blob/master/es2015.md#programs
+
 [dfn-literal]: https://github.com/syntax-tree/mdast#literal
 
+[remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[mdx]: https://mdxjs.com
+
+[api-mdx-expression-from-markdown]: #mdxexpressionfrommarkdown
+
+[api-mdx-expression-to-markdown]: #mdxexpressiontomarkdown
+
+[api-mdx-flow-expression]: #mdxflowexpression
+
+[api-mdx-text-expression]: #mdxtextexpression
+
+[api-mdx-flow-expression-hast]: #mdxflowexpressionhast
+
+[api-mdx-text-expression-hast]: #mdxtextexpressionhast
+
 [dfn-flow-content]: #flowcontent-mdx-expression
 
 [dfn-phrasing-content]: #phrasingcontent-mdx-expression
-
-[remark-mdx]: https://mdxjs.com/packages/remark-mdx/
-
-[mdx]: https://mdxjs.com

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24567

increased by38.73%

Dev dependency count

12

decreased by-14.29%

Number of package files

8

increased by33.33%

Lines of code

285

increased by112.69%

Number of lines in readme file

498

increased by29.69%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes