xastscript - npm Package Compare versions

Comparing version 2.0.1 to 2.1.0

index.js

@@ -7,7 +7,10 @@ 'use strict'
 function x(name, attributes) {
-  var node = {type: 'element', name: name, attributes: {}, children: []}
+  var node =
+    name == null
+      ? {type: 'root', children: []}
+      : {type: 'element', name: name, attributes: {}, children: []}
   var index = 1
   var key
 
-  if (typeof name !== 'string' || !name) {
+  if (name != null && typeof name !== 'string') {
     throw new Error('Expected element name, got `' + name + '`')
@@ -19,2 +22,3 @@ }
     if (
+      name == null ||
       typeof attributes === 'string' ||
@@ -56,3 +60,7 @@ typeof attributes === 'number' ||
   } else if (typeof value === 'object' && value.type) {
-    nodes.push(value)
+    if (value.type === 'root') {
+      addChild(nodes, value.children)
+    } else {
+      nodes.push(value)
+    }
   } else {
@@ -59,0 +67,0 @@ throw new TypeError('Expected node, nodes, string, got `' + value + '`')

package.json

 {
   "name": "xastscript",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "xast utility to create trees",
@@ -37,2 +37,6 @@ "license": "MIT",
   "devDependencies": {
+    "@babel/core": "^7.0.0",
+    "@babel/plugin-syntax-jsx": "^7.0.0",
+    "@babel/plugin-transform-react-jsx": "^7.0.0",
+    "buble": "^0.20.0",
     "dtslint": "^4.0.0",
@@ -44,10 +48,12 @@ "nyc": "^15.0.0",
     "tape": "^5.0.0",
+    "unist-builder": "^2.0.0",
     "xo": "^0.34.0"
   },
   "scripts": {
+    "generate": "node script/generate-jsx",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test",
-    "test-coverage": "nyc --reporter lcov tape test.js",
+    "test-coverage": "nyc --reporter lcov tape test/index.js",
     "test-types": "dtslint types",
-    "test": "npm run format && npm run test-coverage && npm run test-types"
+    "test": "npm run generate && npm run format && npm run test-coverage && npm run test-types"
   },
@@ -54,0 +60,0 @@ "nyc": {

readme.md

@@ -51,3 +51,3 @@ # xastscript
 console.log(
-  u('root', [
+  x(null, [
     u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"'),
@@ -146,6 +146,12 @@ x('album', [
 
-### `x(name[, attributes][, …children])`
+### `x(name?[, attributes][, …children])`
 
 Create XML *[trees][tree]* in **[xast][]**.
 
+##### Signatures
+
+*   `x(): root`
+*   `x(null[, …children]): root`
+*   `x(name[, attributes][, …children]): element`
+
 ##### Parameters
@@ -155,4 +161,6 @@
 
-Qualified name (`string`).
+Qualified name (`string`, optional).
 Case sensitive and can contain a namespace prefix (such as `rdf:RDF`).
+When string, an [`Element`][element] is built.
+When nullish, a [`Root`][root] is built instead.
 
@@ -165,13 +173,66 @@ ###### `attributes`
 
-Cannot be omitted if `children` is a `Node`.
+Cannot be given if building a [`Root`][root].
+Cannot be omitted when building an [`Element`][element] if the first child is a
+[`Node`][node].
 
 ###### `children`
 
-(Lists of) child nodes (`string`, `Node`, `Array.<children>`, optional).
-When strings are encountered, they are mapped to [`text`][text] nodes.
+(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.
 
 ##### Returns
 
-[`Element`][element].
+[`Element`][element] or [`Root`][root].
 
+## JSX
+
+`xastscript` can be used as a pragma for JSX.
+The example above (omitting the second) can then be written like so:
+
+```jsx
+var u = require('unist-builder')
+var x = require('xastscript')
+
+console.log(
+  <album id={123}>
+    <name>Born in the U.S.A.</name>
+    <artist>Bruce Springsteen</artist>
+    <releasedate>1984-04-06</releasedate>
+  </album>
+)
+
+console.log(
+  <>
+    {u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"')}
+    <album>
+      {u('comment', 'Great album!')}
+      <name>Born in the U.S.A.</name>
+      <description>{u('cdata', '3 < 5 & 8 > 13')}</description>
+    </album>
+  </>
+)
+```
+
+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).
+
+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] (in classic
+mode), and pass `pragma: 'x'` and `pragmaFrag: 'null'`.
+
+Babel also lets you configure this in a script:
+
+```jsx
+/** @jsx x */
+/** @jsxFrag null */
+var x = require('xastscript')
+
+console.log(<music />)
+```
+
 ## Security
@@ -210,5 +271,5 @@
 
-[build-badge]: https://img.shields.io/travis/syntax-tree/xastscript.svg
+[build-badge]: https://github.com/syntax-tree/xastscript/workflows/main/badge.svg
 
-[build]: https://travis-ci.org/syntax-tree/xastscript
+[build]: https://github.com/syntax-tree/xastscript/actions
 
@@ -257,2 +318,6 @@ [coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/xastscript.svg
 
+[node]: https://github.com/syntax-tree/unist#node
+
+[root]: https://github.com/syntax-tree/xast#root
+
 [element]: https://github.com/syntax-tree/xast#element
@@ -265,1 +330,7 @@
 [h]: https://github.com/syntax-tree/hastscript
+
+[bublé]: https://github.com/Rich-Harris/buble
+
+[babel]: https://github.com/babel/babel
+
+[babel-jsx]: https://github.com/babel/babel/tree/main/packages/babel-plugin-transform-react-jsx

types/index.d.ts

 // TypeScript Version: 3.7
 
-import {Attributes, Element, Node} from 'xast'
+import {Element, Node} from 'xast'
 
-type Children = string | Node | Children[]
+type Children = string | Node | number | Children[]
 
+type Primitive = null | undefined | string | number
+
 /**
+ * Extending Attributes to Support JS Primitive Types
+ */
+type Attributes = Record<string, Primitive>
+
+/**
  * Create XML trees in xast.
@@ -9,0 +16,0 @@ *

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

14017

increased by22.41%

Lines of code

86

increased by17.81%

Number of lines in readme file

330

increased by27.41%

Worsened metrics

Dev dependency count

12

increased by71.43%

No dependency changes