Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

xastscript

Package Overview
Dependencies
Maintainers
2
Versions
11
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

xastscript

xast utility to create trees

  • 4.0.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
4.2K
increased by8.32%
Maintainers
2
Weekly downloads
 
Created
Source

xastscript

Build Coverage Downloads Size Sponsors Backers Chat

xast utility to create trees with ease.

Contents

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 when creating any unist nodes and hastscript when creating hast (HTML) nodes.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install xastscript

In Deno with esm.sh:

import {x} from 'https://esm.sh/xastscript@4'

In browsers with esm.sh:

<script type="module">
  import {x} from 'https://esm.sh/xastscript@4?bundle'
</script>

Use

import {u} from 'unist-builder'
import {x} from 'xastscript'

// Children as an array:
console.log(
  x('album', {id: 123}, [
    x('name', 'Born in the U.S.A.'),
    x('artist', 'Bruce Springsteen'),
    x('releasedate', '1984-04-06')
  ])
)

// Children as arguments:
console.log(
  x(
    'album',
    {id: 123},
    x('name', 'Exile in Guyville'),
    x('artist', 'Liz Phair'),
    x('releasedate', '1993-06-22')
  )
)

// For other xast nodes, such as comments, instructions, doctypes, or cdata
// can be created with unist-builder:
console.log(
  x(null, [
    u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"'),
    x('album', [
      u('comment', 'Great album!'),
      x('name', 'Born in the U.S.A.'),
      x('description', [u('cdata', '3 < 5 & 8 > 13')])
    ])
  ])
)

Yields:

{
  type: 'element',
  name: 'album',
  attributes: {id: '123'},
  children: [
    {
      type: 'element',
      name: 'name',
      attributes: {},
      children: [{type: 'text', value: 'Born in the U.S.A.'}]
    },
    {
      type: 'element',
      name: 'artist',
      attributes: {},
      children: [{type: 'text', value: 'Bruce Springsteen'}]
    },
    {
      type: 'element',
      name: 'releasedate',
      attributes: {},
      children: [{type: 'text', value: '1984-04-06'}]
    }
  ]
}
{
  type: 'element',
  name: 'album',
  attributes: {id: '123'},
  children: [
    {
      type: 'element',
      name: 'name',
      attributes: {},
      children: [{type: 'text', value: 'Exile in Guyville'}]
    },
    {
      type: 'element',
      name: 'artist',
      attributes: {},
      children: [{type: 'text', value: 'Liz Phair'}]
    },
    {
      type: 'element',
      name: 'releasedate',
      attributes: {},
      children: [{type: 'text', value: '1993-06-22'}]
    }
  ]
}
{
  type: 'root',
  children: [
    {type: 'instruction', name: 'xml', value: 'version="1.0" encoding="UTF-8"'},
    {
      type: 'element',
      name: 'album',
      attributes: {},
      children: [
        {type: 'comment', value: 'Great album!'},
        {
          type: 'element',
          name: 'name',
          attributes: {},
          children: [{type: 'text', value: 'Born in the U.S.A.'}]
        },
        {
          type: 'element',
          name: 'description',
          attributes: {},
          children: [{type: 'cdata', value: '3 < 5 & 8 > 13'}]
        }
      ]
    }
  ]
}

API

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) with an importSource option or similar.

x(name?[, attributes][, …children])

Create xast trees.

Signatures
  • x(): root
  • x(null[, …children]): root
  • x(name[, attributes][, …children]): element
Parameters
name

Qualified name (string, optional).

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.

attributes

Attributes of the element (Attributes, optional).

children

Children of the node (Array<Child> or Child, optional).

Returns

Created tree (Result).

Element when a name is passed, otherwise Root.

Attributes

Map of attributes (TypeScript type).

Nullish (null or undefined) or NaN values are ignored, other values are turned to strings.

Type
type Attributes = Record<string, boolean | number | string | null | undefined>

Child

(Lists of) children (TypeScript type).

When strings or numbers are encountered, they are turned into Text nodes. Root nodes are treated as “fragments”, meaning that their children are used instead.

Type
type Child =
  | Array<Node | boolean | number | string | null | undefined>
  | Node
  | boolean
  | number
  | string
  | null
  | undefined

Result

Result from a x call (TypeScript type).

Type
type Result = Element | Root

Syntax tree

The syntax tree is xast.

JSX

This package can be used with JSX. You should use the automatic JSX runtime set to xastscript.

🪦 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:

/** @jsxImportSource xastscript */

import {u} from 'unist-builder'

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>
  </>
)

Types

This package is fully typed with TypeScript. It exports the additional types Attributes, Child, and Result.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, xastscript@^4, compatible with Node.js 16.

Security

XML can be a dangerous language: don’t trust user-provided data.

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer

Keywords

FAQs

Package last updated on 18 Jul 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc