xastscript - npm Package Compare versions

Comparing version 3.1.0 to 3.1.1

index.d.ts

 export {x} from './lib/index.js'
+export type Child = import('./lib/index.js').Child
+export type Attributes = import('./lib/index.js').Attributes
+export type Result = import('./lib/index.js').Result

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').Child} Child
+ * @typedef {import('./lib/index.js').Attributes} Attributes
+ * @typedef {import('./lib/index.js').Result} Result
  */
 
 export {x} from './lib/index.js'

jsx-dev-runtime.d.ts

@@ -0,1 +1,2 @@
+export * from './lib/jsx-automatic.js'
 export {Fragment} from './jsx-runtime.js'
@@ -5,5 +6,6 @@ export function jsxDEV(
   props: {
-    children?: XChild
+    children?: Child
   },
-  ...unused: unknown[]
+  key?: string,
+  ...unused: Array<unknown>
 ): Root
@@ -13,7 +15,8 @@ export function jsxDEV(
   props: JSXProps,
-  ...unused: unknown[]
+  key?: string,
+  ...unused: Array<unknown>
 ): Element
 export type Element = import('xast').Element
 export type Root = import('xast').Root
-export type XChild = import('./lib/index.js').XChild
+export type Child = import('./lib/index.js').Child
 export type JSXProps = import('./lib/runtime.js').JSXProps

jsx-dev-runtime.js

 /**
  * @typedef {import('xast').Element} Element
  * @typedef {import('xast').Root} Root
- * @typedef {import('./lib/index.js').XChild} XChild
+ * @typedef {import('./lib/index.js').Child} Child
  * @typedef {import('./lib/runtime.js').JSXProps} JSXProps
  */
 
-import {jsx} from './jsx-runtime.js'
+import {jsx} from './lib/runtime.js'
 
+// Export `JSX` as a global for TypeScript.
+export * from './lib/jsx-automatic.js'
+
 export {Fragment} from './jsx-runtime.js'
@@ -16,6 +19,6 @@
    * @type {{
-   *   (name: null|undefined, props: {children?: XChild}, ...unused: unknown[]): Root
-   *   (name: string, props: JSXProps, ...unused: unknown[]): Element
+   *   (name: null | undefined, props: {children?: Child}, key?: string, ...unused: Array<unknown>): Root
+   *   (name: string, props: JSXProps, key?: string, ...unused: Array<unknown>): Element
    * }}
    */
   (jsx)

jsx-runtime.d.ts

@@ -1,1 +0,2 @@
-export * from './lib/runtime.js'
+export * from './lib/jsx-automatic.js'
+export {jsx, jsxs, Fragment} from './lib/runtime.js'

jsx-runtime.js

@@ -5,2 +5,5 @@ /**
 
-export * from './lib/runtime.js'
+// Export `JSX` as a global for TypeScript.
+export * from './lib/jsx-automatic.js'
+
+export {jsx, jsxs, Fragment} from './lib/runtime.js'

lib/index.d.ts

 export function x(): Root
-export function x(name: null | undefined, ...children: Array<XChild>): Root
+export function x(name: null | undefined, ...children: Array<Child>): Root
 export function x(
   name: string,
-  attributes: XAttributes,
-  ...children: Array<XChild>
+  attributes?: Attributes,
+  ...children: Array<Child>
 ): Element
-export function x(name: string, ...children: Array<XChild>): Element
+export function x(name: string, ...children: Array<Child>): Element
 export namespace x {
@@ -20,14 +20,32 @@ namespace JSX {
 export type Element = import('xast').Element
-export type Child = Root['children'][number]
-export type Node = Child | Root
-export type XResult = Root | Element
-export type XValue = string | number | boolean | null | undefined
+export type Content = Root['children'][number]
 /**
- * Attributes to support JS primitive types
+ * Any concrete `xast` node.
  */
-export type XAttributes = {
-  [attribute: string]: XValue
+export type Node = Content | Root
+/**
+ * Result from a `x` call.
+ */
+export type Result = Root | Element
+/**
+ * Attribute value
+ */
+export type Value = string | number | boolean | null | undefined
+/**
+ * Acceptable value for element properties.
+ */
+export type Attributes = {
+  [attribute: string]: Value
 }
-export type XPrimitiveChild = string | number | null | undefined
-export type XArrayChild = Array<Node | XPrimitiveChild>
-export type XChild = Node | XPrimitiveChild | (Node | XPrimitiveChild)[]
+/**
+ * Primitive children, either ignored (nullish), or turned into text nodes.
+ */
+export type PrimitiveChild = string | number | null | undefined
+/**
+ * List of children.
+ */
+export type ArrayChild = Array<Node | PrimitiveChild>
+/**
+ * Acceptable child value.
+ */
+export type Child = Node | PrimitiveChild | (Node | PrimitiveChild)[]

lib/index.js

 /**
  * @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 {Root['children'][number]} Content
+ * @typedef {Content | Root} Node
+ *   Any concrete `xast` node.
  *
- * @typedef {string|number|null|undefined} XPrimitiveChild
- * @typedef {Array<Node|XPrimitiveChild>} XArrayChild
- * @typedef {Node|XPrimitiveChild|XArrayChild} XChild
+ * @typedef {Root | Element} Result
+ *   Result from a `x` call.
+ *
+ * @typedef {string | number | boolean | null | undefined} Value
+ *   Attribute value
+ * @typedef {{[attribute: string]: Value}} Attributes
+ *   Acceptable value for element properties.
+ *
+ * @typedef {string | number | null | undefined} PrimitiveChild
+ *   Primitive children, either ignored (nullish), or turned into text nodes.
+ * @typedef {Array<Node | PrimitiveChild>} ArrayChild
+ *   List of children.
+ * @typedef {Node | PrimitiveChild | ArrayChild} Child
+ *   Acceptable child value.
+ *
  * @typedef {import('./jsx-classic.js').Element} x.JSX.Element
@@ -22,5 +35,14 @@ * @typedef {import('./jsx-classic.js').IntrinsicAttributes} x.JSX.IntrinsicAttributes
  *
- * @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.
+ * @param name
+ *   Qualified name.
+ *
+ *   Case sensitive and can contain a namespace prefix (such as `rdf:RDF`).
+ *   When string, an `Element` is built.
+ *   When nullish, a `Root` is built instead.
+ * @param attributes
+ *   Attributes of the element.
+ * @param children
+ *   Children of the node.
+ * @returns
+ *   `Element` or `Root`.
  */
@@ -31,5 +53,5 @@ export const x =
    *   (): Root
-   *   (name: null|undefined, ...children: Array<XChild>): Root
-   *   (name: string, attributes: XAttributes, ...children: Array<XChild>): Element
-   *   (name: string, ...children: Array<XChild>): Element
+   *   (name: null | undefined, ...children: Array<Child>): Root
+   *   (name: string, attributes?: Attributes, ...children: Array<Child>): Element
+   *   (name: string, ...children: Array<Child>): Element
    * }}
@@ -39,12 +61,10 @@ */
     /**
-     * Hyperscript compatible DSL for creating virtual xast trees.
-     *
-     * @param {string|null} [name]
-     * @param {XAttributes|XChild} [attributes]
-     * @param {Array<XChild>} children
-     * @returns {XResult}
+     * @param {string | null | undefined} [name]
+     * @param {Attributes | Child | null | undefined} [attributes]
+     * @param {Array<Child>} children
+     * @returns {Result}
      */
     function (name, attributes, ...children) {
       let index = -1
-      /** @type {XResult} */
+      /** @type {Result} */
       let node
@@ -92,4 +112,10 @@
 /**
+ * Add children.
+ *
  * @param {Array<Child>} nodes
- * @param {XChild} value
+ *   List of nodes.
+ * @param {Child} value
+ *   Child.
+ * @returns {void}
+ *   Nothing.
  */
@@ -119,4 +145,8 @@ function addChild(nodes, value) {
 /**
- * @param {XAttributes|XChild} value
- * @returns {value is XAttributes}
+ * Check if `value` is `Attributes`.
+ *
+ * @param {Attributes | Child} value
+ *   Value.
+ * @returns {value is Attributes}
+ *   Whether `value` is `Attributes`.
  */
@@ -123,0 +153,0 @@ function isAttributes(value) {

lib/jsx-automatic.d.ts

 /* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
-import {XAttributes, XChild, XResult} from './index.js'
+import {Attributes, Child, Result} from './index.js'
 
@@ -8,3 +8,3 @@ export namespace JSX {
    */
-  type Element = XResult
+  type Element = Result
 
@@ -28,3 +28,3 @@ /**
     [name: string]:
-      | XAttributes
+      | Attributes
       | {
@@ -34,3 +34,3 @@ /**
            */
-          children?: XChild
+          children?: Child
         }
@@ -37,0 +37,0 @@ }

lib/jsx-classic.d.ts

 /* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
-import {XAttributes, XChild, XResult} from './index.js'
+import {Attributes, Child, Result} from './index.js'
 
@@ -13,3 +13,3 @@ /**
  */
-export type Element = XResult
+export type Element = Result
 
@@ -33,3 +33,3 @@ /**
   [name: string]:
-    | XAttributes
+    | Attributes
     | {
@@ -39,3 +39,3 @@ /**
          */
-        [children]?: XChild
+        [children]?: Child
       }
@@ -42,0 +42,0 @@ }

lib/runtime.d.ts

@@ -1,6 +0,5 @@
-export * from './jsx-automatic.js'
 export function jsx(
   name: null | undefined,
   props: {
-    children?: XChild
+    children?: Child
   },
@@ -13,3 +12,3 @@ key?: string
   props: {
-    children?: XChild
+    children?: Child
   },
@@ -19,10 +18,9 @@ key?: string
 export function jsxs(name: string, props: JSXProps, key?: string): Element
-/** @type {null} */
 export const Fragment: null
 export type Element = import('./index.js').Element
 export type Root = import('./index.js').Root
-export type XResult = import('./index.js').XResult
-export type XChild = import('./index.js').XChild
-export type XAttributes = import('./index.js').XAttributes
-export type XValue = import('./index.js').XValue
+export type Result = import('./index.js').Result
+export type Child = import('./index.js').Child
+export type Attributes = import('./index.js').Attributes
+export type Value = import('./index.js').Value
 export type JSXProps = {
@@ -40,5 +38,5 @@ [x: string]:
     | import('xast').Text
-    | import('./index.js').XArrayChild
+    | import('./index.js').ArrayChild
     | null
     | undefined
 }

lib/runtime.js

 /**
  * @typedef {import('./index.js').Element} Element
  * @typedef {import('./index.js').Root} Root
- * @typedef {import('./index.js').XResult} XResult
- * @typedef {import('./index.js').XChild} XChild
- * @typedef {import('./index.js').XAttributes} XAttributes
- * @typedef {import('./index.js').XValue} XValue
+ * @typedef {import('./index.js').Result} Result
+ * @typedef {import('./index.js').Child} Child
+ * @typedef {import('./index.js').Attributes} Attributes
+ * @typedef {import('./index.js').Value} Value
  *
- * @typedef {{[x: string]: XValue|XChild}} JSXProps
+ * @typedef {{[x: string]: Value | Child}} JSXProps
  */
@@ -14,10 +14,20 @@
 
-// Export `JSX` as a global for TypeScript.
-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.
+ * @param name
+ *   Qualified name.
+ *
+ *   Case sensitive and can contain a namespace prefix (such as `rdf:RDF`).
+ *   When string, an `Element` is built.
+ *   When nullish, a `Root` is built instead.
+ * @param props
+ *   Map of attributes.
+ *
+ *   Nullish (`null` or `undefined`) or `NaN` values are ignored, other values
+ *   are turned to strings.
+ *
+ *   Cannot be given if building a `Root`.
+ *   Cannot be omitted when building an `Element` if the first child is a
+ *   `Node`.
  */
@@ -27,3 +37,3 @@ export const jsx =
    * @type {{
-   *   (name: null|undefined, props: {children?: XChild}, key?: string): Root
+   *   (name: null | undefined, props: {children?: Child}, key?: string): Root
    *   (name: string, props: JSXProps, key?: string): Element
@@ -34,5 +44,5 @@ * }}
     /**
-     * @param {string|null} name
-     * @param {XAttributes & {children?: XChild}} props
-     * @returns {XResult}
+     * @param {string | null} name
+     * @param {Attributes & {children?: Child}} props
+     * @returns {Result}
      */
@@ -47,3 +57,2 @@ function (name, props) {
 
-/** @type {null} */
 export const Fragment = null

package.json

 {
   "name": "xastscript",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "xast utility to create trees",
@@ -51,8 +51,5 @@ "license": "MIT",
   "devDependencies": {
-    "@babel/core": "^7.0.0",
-    "@babel/plugin-syntax-jsx": "^7.0.0",
-    "@babel/plugin-transform-react-jsx": "^7.0.0",
-    "@types/babel__core": "^7.0.0",
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "c8": "^7.0.0",
+    "esast-util-from-js": "^1.0.0",
     "estree-util-build-jsx": "^2.0.0",
@@ -63,17 +60,15 @@ "estree-util-to-js": "^1.0.0",
     "remark-preset-wooorm": "^9.0.0",
-    "rimraf": "^3.0.0",
-    "tape": "^5.0.0",
-    "tsd": "^0.23.0",
+    "tsd": "^0.25.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
     "unist-builder": "^3.0.0",
-    "xo": "^0.52.0"
+    "xo": "^0.53.0"
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"{script/**,test/**,}*.d.ts\" \"lib/{index,runtime}.d.ts\" && tsc && tsd && type-coverage",
-    "generate": "node script/generate-jsx",
+    "generate": "node script/generate-jsx.js",
+    "build": "tsc --build --clean && tsc --build && tsd && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
-    "test-api": "node test/index.js",
-    "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test/index.js",
+    "test-api": "node --conditions development test/index.js",
+    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
     "test": "npm run generate && npm run build && npm run format && npm run test-coverage"
@@ -80,0 +75,0 @@ },

readme.md

@@ -21,2 +21,6 @@ # xastscript
     *   [`x(name?[, attributes][, …children])`](#xname-attributes-children)
+    *   [`Attributes`](#attributes-1)
+    *   [`Child`](#child)
+    *   [`Result`](#result)
+*   [Syntax tree](#syntax-tree)
 *   [JSX](#jsx)
@@ -48,3 +52,3 @@ *   [Types](#types)
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:
+In Node.js (version 14.14+ and 16.0+), install with [npm][]:
 
@@ -192,8 +196,8 @@ ```sh
 
-This package exports the identifier `x`.
+This package exports the identifier [`x`][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.
+You can pass `xastscript` to your build tool (TypeScript, Babel, SWC) with an
+`importSource` option or similar.
 
@@ -215,2 +219,3 @@ ### `x(name?[, attributes][, …children])`
 Qualified name (`string`, optional).
+
 Case sensitive and can contain a namespace prefix (such as `rdf:RDF`).
@@ -222,32 +227,77 @@ When string, an [`Element`][element] is built.
 
-Map of attributes (`Record<string, string|number|boolean|null|undefined>`,
-optional).
+Attributes of the element ([`Attributes`][attributes], optional).
+
+###### `children`
+
+Children of the node ([`Child`][child] or `Array<Child>`, optional).
+
+##### Returns
+
+Created tree ([`Result`][result]).
+
+[`Element`][element] when a `name` is passed, otherwise [`Root`][root].
+
+### `Attributes`
+
+Map of attributes (TypeScript type).
+
 Nullish (`null` or `undefined`) or `NaN` values are ignored, other values are
 turned to strings.
 
-Cannot be given if building a [`Root`][root].
-Cannot be omitted when building an [`Element`][element] if the first child is a
-[`Node`][node].
+###### Type
 
-###### `children`
+```ts
+type Attributes = Record<string, string | number | boolean | null | undefined>
+```
 
-(Lists of) children (`string`, `number`, `Node`, `Array<children>`, optional).
-When strings or numbers are encountered, they are mapped to [`Text`][text]
+### `Child`
+
+(Lists of) children (TypeScript type).
+
+When strings or numbers are encountered, they are turned into [`Text`][text]
 nodes.
-If a [`Root`][root] node is encountered, its children are used instead.
+[`Root`][root] nodes are treated as “fragments”, meaning that their children
+are used instead.
 
-##### Returns
+###### Type
 
-[`Element`][element] or [`Root`][root].
+```ts
+type Child =
+  | string
+  | number
+  | null
+  | undefined
+  | Node
+  | Array<string | number | null | undefined | Node>
+```
 
+### `Result`
+
+Result from a `x` call (TypeScript type).
+
+###### Type
+
+```ts
+type Result = Root | Element
+```
+
+## Syntax tree
+
+The syntax tree is [xast][].
+
 ## 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`).
+This package can be used with JSX.
+You should use the automatic JSX runtime set to `xastscript`.
 
-The example above (omitting the second) can then be written like so:
+> 🪦 **Legacy**: you can also use the classic JSX runtime, but this is not
+> recommended.
+> To do so, import `x` yourself and define it as the pragma (plus set the
+> fragment to `null`).
 
+The Use example above (omitting the second) can then be written like so:
+
 ```jsx
 /** @jsxImportSource x */
+
 import {u} from 'unist-builder'
@@ -275,28 +325,7 @@
 
-You can use [`estree-util-build-jsx`][estree-util-build-jsx] to compile JSX
-away.
-
-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:
-
-```jsx
-/** @jsx x @jsxFrag null */
-import {x} from 'xastscript'
-
-console.log(<music />)
-```
-
-For [TypeScript][], this can be done by setting `"jsx": "react"`,
-`"jsxFactory": "x"`, and `"jsxFragmentFactory": "null"` in the compiler options.
-For more details on configuring JSX for TypeScript, see the
-[TypeScript JSX handbook page][typescript-jsx].
-TypeScript also lets you configure this from code as shown with Babel above.
-
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional types `Child` and `Attributes`.
+It exports the additional types [`Attributes`][attributes], [`Child`][child],
+and [`Result`][result].
 
@@ -307,3 +336,3 @@ ## Compatibility
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.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.
@@ -392,4 +421,2 @@
 
-[node]: https://github.com/syntax-tree/unist#node
-
 [root]: https://github.com/syntax-tree/xast#root
@@ -405,8 +432,8 @@
 
-[babel]: https://github.com/babel/babel
+[x]: #xname-attributes-children
 
-[babel-jsx]: https://github.com/babel/babel/tree/main/packages/babel-plugin-transform-react-jsx
+[attributes]: #attributes-1
 
-[typescript-jsx]: https://www.typescriptlang.org/docs/handbook/jsx.html
+[child]: #child
 
-[estree-util-build-jsx]: https://github.com/syntax-tree/estree-util-build-jsx
+[result]: #result

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

Improved metrics

Total package byte prevSize

26403

increased by1.59%

Dev dependency count

13

decreased by-27.78%

Lines of code

433

increased by17.66%

Number of lines in readme file

431

increased by6.68%

No dependency changes