xastscript - npm Package Compare versions

Comparing version 3.0.0 to 3.0.1

index.js

 /**
- * @typedef {import('./lib/index.js').XChild}} Child Acceptable child value
- * @typedef {import('./lib/index.js').XAttributes}} Attributes Acceptable attributes value.
+ * @typedef {import('./lib/index.js').XChild}} Child
+ *   Acceptable child value
+ * @typedef {import('./lib/index.js').XAttributes}} Attributes
+ *   Acceptable attributes value.
  */
 
 export {x} from './lib/index.js'

lib/index.d.ts

@@ -1,37 +0,16 @@
-/**
- * @typedef {import('xast').Root} Root
- * @typedef {import('xast').Element} Element
- * @typedef {Root['children'][number]} Child
- * @typedef {Child|Root} Node
- * @typedef {Root|Element} XResult
- * @typedef {string|number|boolean|null|undefined} XValue
- * @typedef {{[attribute: string]: XValue}} XAttributes Attributes to support JS primitive types
- *
- * @typedef {string|number|null|undefined} XPrimitiveChild
- * @typedef {Array.<Node|XPrimitiveChild>} XArrayChild
- * @typedef {Node|XPrimitiveChild|XArrayChild} XChild
- * @typedef {import('./jsx-classic').Element} x.JSX.Element
- * @typedef {import('./jsx-classic').IntrinsicAttributes} x.JSX.IntrinsicAttributes
- * @typedef {import('./jsx-classic').IntrinsicElements} x.JSX.IntrinsicElements
- * @typedef {import('./jsx-classic').ElementChildrenAttribute} x.JSX.ElementChildrenAttribute
- */
-/**
- * Create XML trees in xast.
- *
- * @param name Qualified name. Case sensitive and can contain a namespace prefix (such as `rdf:RDF`). Pass `null|undefined` to build a root.
- * @param attributes Map of attributes. Nullish (null or undefined) or NaN values are ignored, other values (strings, booleans) are cast to strings.
- * @param children (Lists of) child nodes. When strings are encountered, they are mapped to Text nodes.
- */
-export const x: {
-  (): Root
-  (name: null | undefined, ...children: XChild[]): Root
-  (name: string, attributes: XAttributes, ...children: XChild[]): Element
-  (name: string, ...children: XChild[]): Element
-}
+export function x(): Root
+export function x(name: null | undefined, ...children: Array<XChild>): Root
+export function x(
+  name: string,
+  attributes: XAttributes,
+  ...children: Array<XChild>
+): Element
+export function x(name: string, ...children: Array<XChild>): Element
 export namespace x {
   namespace JSX {
-    type Element = import('./jsx-classic').Element
-    type IntrinsicAttributes = import('./jsx-classic').IntrinsicAttributes
-    type IntrinsicElements = import('./jsx-classic').IntrinsicElements
-    type ElementChildrenAttribute = import('./jsx-classic').ElementChildrenAttribute
+    type Element = import('./jsx-classic.js').Element
+    type IntrinsicAttributes = import('./jsx-classic.js').IntrinsicAttributes
+    type IntrinsicElements = import('./jsx-classic.js').IntrinsicElements
+    type ElementChildrenAttribute =
+      import('./jsx-classic.js').ElementChildrenAttribute
   }
@@ -38,0 +17,0 @@ }

lib/index.js

@@ -11,8 +11,8 @@ /**
  * @typedef {string|number|null|undefined} XPrimitiveChild
- * @typedef {Array.<Node|XPrimitiveChild>} XArrayChild
+ * @typedef {Array<Node|XPrimitiveChild>} XArrayChild
  * @typedef {Node|XPrimitiveChild|XArrayChild} XChild
- * @typedef {import('./jsx-classic').Element} x.JSX.Element
- * @typedef {import('./jsx-classic').IntrinsicAttributes} x.JSX.IntrinsicAttributes
- * @typedef {import('./jsx-classic').IntrinsicElements} x.JSX.IntrinsicElements
- * @typedef {import('./jsx-classic').ElementChildrenAttribute} x.JSX.ElementChildrenAttribute
+ * @typedef {import('./jsx-classic.js').Element} x.JSX.Element
+ * @typedef {import('./jsx-classic.js').IntrinsicAttributes} x.JSX.IntrinsicAttributes
+ * @typedef {import('./jsx-classic.js').IntrinsicElements} x.JSX.IntrinsicElements
+ * @typedef {import('./jsx-classic.js').ElementChildrenAttribute} x.JSX.ElementChildrenAttribute
  */
@@ -31,5 +31,5 @@
    *   (): Root
-   *   (name: null|undefined, ...children: XChild[]): Root
-   *   (name: string, attributes: XAttributes, ...children: XChild[]): Element
-   *   (name: string, ...children: XChild[]): Element
+   *   (name: null|undefined, ...children: Array<XChild>): Root
+   *   (name: string, attributes: XAttributes, ...children: Array<XChild>): Element
+   *   (name: string, ...children: Array<XChild>): Element
    * }}
@@ -43,15 +43,13 @@ */
      * @param {XAttributes|XChild} [attributes]
-     * @param {XChild[]} children
+     * @param {Array<XChild>} children
      * @returns {XResult}
      */
     function (name, attributes, ...children) {
-      var index = -1
+      let index = -1
       /** @type {XResult} */
-      var node
-      /** @type {string} */
-      var key
+      let node
 
       if (name === undefined || name === null) {
         node = {type: 'root', children: []}
-        // @ts-ignore Root builder doesn’t accept attributes.
+        // @ts-expect-error Root builder doesn’t accept attributes.
         children.unshift(attributes)
@@ -62,2 +60,5 @@ } else if (typeof name === 'string') {
         if (isAttributes(attributes)) {
+          /** @type {string} */
+          let key
+
           for (key in attributes) {
@@ -71,3 +72,3 @@ // Ignore nullish and NaN values.
             ) {
-              // @ts-ignore Pretty sure we just set it.
+              // @ts-expect-error Pretty sure we just set it.
               node.attributes[key] = String(attributes[key])
@@ -93,7 +94,7 @@ }
 /**
- * @param {Array.<Child>} nodes
+ * @param {Array<Child>} nodes
  * @param {XChild} value
  */
 function addChild(nodes, value) {
-  var index = -1
+  let index = -1
 
@@ -100,0 +101,0 @@ if (value === undefined || value === null) {

lib/jsx-automatic.d.ts

@@ -0,1 +1,2 @@
+/* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
 import {XAttributes, XChild, XResult} from './index.js'
@@ -14,2 +15,4 @@
 
+  /* eslint-disable @typescript-eslint/consistent-type-definitions -- interfaces are required here */
+
   /**
@@ -43,2 +46,4 @@ * This defines the prop types for known elements.
   }
+
+  /* eslint-enable @typescript-eslint/consistent-type-definitions */
 }

lib/jsx-classic.d.ts

@@ -0,1 +1,2 @@
+/* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
 import {XAttributes, XChild, XResult} from './index.js'
@@ -19,2 +20,4 @@
 
+/* eslint-disable @typescript-eslint/consistent-type-definitions -- interfaces are required here */
+
 /**
@@ -48,1 +51,3 @@ * This defines the prop types for known elements.
 }
+
+/* eslint-enable @typescript-eslint/consistent-type-definitions */

lib/runtime.d.ts

 export * from './jsx-automatic.js'
-/**
- * Create XML trees in xast through JSX.
- *
- * @param name Qualified name. Case sensitive and can contain a namespace prefix (such as `rdf:RDF`). Pass `null|undefined` to build a root.
- * @param props Map of attributes. Nullish (null or undefined) or NaN values are ignored, other values (strings, booleans) are cast to strings. `children` can contain one child or a list of children. When strings are encountered, they are mapped to text nodes.
- */
-export const jsx: {
-  (
-    name: null | undefined,
-    props: {
-      children?: XChild
-    },
-    key?: string | undefined
-  ): Root
-  (name: string, props: JSXProps, key?: string | undefined): Element
-}
+export function jsx(
+  name: null | undefined,
+  props: {
+    children?: XChild
+  },
+  key?: string
+): Root
+export function jsx(name: string, props: JSXProps, key?: string): Element
 export function jsxs(
@@ -23,9 +15,5 @@ name: null | undefined,
   },
-  key?: string | undefined
+  key?: string
 ): Root
-export function jsxs(
-  name: string,
-  props: JSXProps,
-  key?: string | undefined
-): Element
+export function jsxs(name: string, props: JSXProps, key?: string): Element
 /** @type {null} */
@@ -32,0 +20,0 @@ export const Fragment: null

lib/runtime.js

@@ -37,3 +37,3 @@ /**
     function (name, props) {
-      var {children, ...properties} = props
+      const {children, ...properties} = props
       return name === null ? x(name, children) : x(name, properties, children)
@@ -40,0 +40,0 @@ }

package.json

 {
   "name": "xastscript",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "xast utility to create trees",
@@ -35,3 +35,5 @@ "license": "MIT",
     "index.d.ts",
-    "index.js"
+    "index.js",
+    "jsx-runtime.d.ts",
+    "jsx-runtime.js"
   ],
@@ -52,16 +54,15 @@ "exports": {
     "@types/tape": "^4.0.0",
-    "astring": "^1.0.0",
-    "buble": "^0.20.0",
     "c8": "^7.0.0",
     "estree-util-build-jsx": "^2.0.0",
+    "estree-util-to-js": "^1.0.0",
     "prettier": "^2.0.0",
-    "remark-cli": "^9.0.0",
-    "remark-preset-wooorm": "^8.0.0",
+    "remark-cli": "^11.0.0",
+    "remark-preset-wooorm": "^9.0.0",
     "rimraf": "^3.0.0",
     "tape": "^5.0.0",
-    "tsd": "^0.14.0",
+    "tsd": "^0.23.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
     "unist-builder": "^3.0.0",
-    "xo": "^0.39.0"
+    "xo": "^0.52.0"
   },
@@ -86,7 +87,3 @@ "scripts": {
   "xo": {
-    "prettier": true,
-    "rules": {
-      "no-var": "off",
-      "prefer-arrow-callback": "off"
-    }
+    "prettier": true
   },
@@ -93,0 +90,0 @@ "remarkConfig": {

readme.md

@@ -11,12 +11,40 @@ # xastscript
 
-**[xast][]** utility to create XML *[trees][tree]* (like [`hastscript`][h] for
-**[hast][]** and [`unist-builder`][u] for **[unist][]**).
+[xast][] utility to create trees with ease.
 
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`x(name?[, attributes][, …children])`](#xname-attributes-children)
+*   [JSX](#jsx)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package is a hyperscript interface (like `createElement` from React and
+such) to help with creating xast trees.
+
+## When should I use this?
+
+You can use this utility in your project when you generate xast syntax trees
+with code.
+It helps because it replaces most of the repetition otherwise needed in a syntax
+tree with function calls.
+
+You can instead use [`unist-builder`][u] when creating any unist nodes and
+[`hastscript`][h] when creating hast (HTML) nodes.
+
 ## Install
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:
 
-[npm][]:
-
 ```sh
@@ -26,2 +54,16 @@ npm install xastscript
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {x} from 'https://esm.sh/xastscript@3'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {x} from 'https://esm.sh/xastscript@3?bundle'
+</script>
+```
+
 ## Use
@@ -150,5 +192,12 @@
 
+This package exports the identifier `x`.
+There is no default export.
+
+The export map supports the automatic JSX runtime.
+You can pass `xastscript` to your build tool (TypeScript, Babel, SWC) as with
+an `importSource` option or similar.
+
 ### `x(name?[, attributes][, …children])`
 
-Create XML *[trees][tree]* in **[xast][]**.
+Create [xast][] trees.
 
@@ -172,3 +221,4 @@ ##### Signatures
 
-Map of attributes (`Object.<*>`, optional).
+Map of attributes (`Record<string, string|number|boolean|null|undefined>`,
+optional).
 Nullish (`null` or `undefined`) or `NaN` values are ignored, other values are
@@ -183,6 +233,6 @@ turned to strings.
 
-(Lists of) children (`string`, `number`, `Node`, `Array.<children>`, optional).
+(Lists of) children (`string`, `number`, `Node`, `Array<children>`, optional).
 When strings or numbers are encountered, they are mapped to [`Text`][text]
 nodes.
-If a [`Root`][root] node is given, its children are used instead.
+If a [`Root`][root] node is encountered, its children are used instead.
 
@@ -195,8 +245,11 @@ ##### Returns
 
-`xastscript` can be used as a pragma for JSX.
+`xastscript` can be used with JSX.
+Either use the automatic runtime set to `xastscript` or import `x` yourself and
+define it as the pragma (plus set the fragment to `null`).
+
 The example above (omitting the second) can then be written like so:
 
 ```jsx
+/** @jsxImportSource x */
 import {u} from 'unist-builder'
-import {x} from 'xastscript'
 
@@ -223,14 +276,11 @@ console.log(
 
-Note that you must still import `xastscript` yourself and configure your
-JavaScript compiler to use the identifier you assign it to as a pragma (and
-pass `null` for fragments).
+You can use [`estree-util-build-jsx`][estree-util-build-jsx] to compile JSX
+away.
 
-For [bublé][], this can be done by setting `jsx: 'x'` and `jsxFragment: 'null'`
-(note that `jsxFragment` is currently only available on the API, not the CLI).
+For [Babel][], use [`@babel/plugin-transform-react-jsx`][babel-jsx] and either
+pass `pragma: 'x'` and `pragmaFrag: 'null'`, or pass `importSource:
+'xastscript'`.
+Alternatively, Babel also lets you configure this with a comment:
+Babel also lets you configure this from code:
 
-For [Babel][], use [`@babel/plugin-transform-react-jsx`][babel-jsx] (in classic
-mode), and pass `pragma: 'x'` and `pragmaFrag: 'null'`.
-
-Babel also lets you configure this in a script:
-
 ```jsx
@@ -246,13 +296,17 @@ /** @jsx x @jsxFrag null */
 For more details on configuring JSX for TypeScript, see the
-[TypeScript JSX handbook page][].
+[TypeScript JSX handbook page][typescript-jsx].
+TypeScript also lets you configure this from code as shown with Babel above.
 
-TypeScript also lets you configure this in a script:
+## Types
 
-```tsx
-/** @jsx x @jsxFrag null */
-import {x} from 'xastscript'
+This package is fully typed with [TypeScript][].
+It exports the additional types `Child` and `Attributes`.
 
-console.log(<music />)
-```
+## Compatibility
 
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
 ## Security
@@ -265,16 +319,16 @@
 *   [`unist-builder`][u]
-    — Create any unist tree
+    — create any unist tree
 *   [`hastscript`][h]
-    — Create a **[hast][]** (HTML or SVG) unist tree
+    — create a hast tree
 *   [`xast-util-to-xml`](https://github.com/syntax-tree/xast-util-to-xml)
-    — Serialize nodes to XML
+    — serialize xast as XML
 *   [`xast-util-from-xml`](https://github.com/syntax-tree/xast-util-from-xml)
-    — Parse from XML
+    — parse xast from XML
 *   [`hast-util-to-xast`](https://github.com/syntax-tree/hast-util-to-xast)
-    — Transform hast (html, svg) to xast (xml)
+    — transform hast to xast
 
 ## Contribute
 
-See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
-started.
+See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
+ways to get started.
 See [`support.md`][support] for ways to get help.
@@ -320,2 +374,8 @@
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
 [license]: license
@@ -325,16 +385,12 @@
 
-[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
+[health]: https://github.com/syntax-tree/.github
 
-[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
+[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
 
-[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
+[support]: https://github.com/syntax-tree/.github/blob/main/support.md
 
-[unist]: https://github.com/syntax-tree/unist
+[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
 
-[hast]: https://github.com/syntax-tree/hast
-
 [xast]: https://github.com/syntax-tree/xast
 
-[tree]: https://github.com/syntax-tree/unist#tree
-
 [node]: https://github.com/syntax-tree/unist#node
@@ -352,4 +408,2 @@
 
-[bublé]: https://github.com/Rich-Harris/buble
-
 [babel]: https://github.com/babel/babel
@@ -359,4 +413,4 @@
 
-[typescript]: https://www.typescriptlang.org
+[typescript-jsx]: https://www.typescriptlang.org/docs/handbook/jsx.html
 
-[typescript jsx handbook page]: https://www.typescriptlang.org/docs/handbook/jsx.html
+[estree-util-build-jsx]: https://github.com/syntax-tree/estree-util-build-jsx

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

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

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

Improved metrics

Total package byte prevSize

24877

increased by1.86%

Dev dependency count

18

decreased by-5.26%

Number of package files

15

increased by15.38%

Number of lines in readme file

404

increased by15.43%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Lines of code

334

decreased by-5.65%

No dependency changes