sveltedoc-parser

The sveltedoc parser

Generate a JSON documentation for a Svelte file

Changelog

[3.0.4] 25.08.2020

• 🛠 [Fixed] Fix issue #5 (slots items have a private access level by default)

[3.0.3] 25.08.2020

• 🛠 [Fixed] Fix issue #28 (Inline event handlers in markup cause errors when used without quotes)
  • Change dependency from htmlparser2 to htmlparser2-svelte special fork of htmlparser2 to handle Svelte specific cases to parse markup

[3.0.2] 24.08.2020

• 🛠 [Fixed] Fix issue #6 (Build a correct component name from a file name)

round.button.svelte -> RoundButton

• 🛠 [Fixed] Fix issue #27 (Events is not exposed from exported functions and arrow functions)
• 🛠 [Fixed] Fix issue #31 (Propogated events in markup should be parsed even it was before handled)
• 🛠 [Fixed] Fix issue #32 (Event is not registered when dispatched from functions used as a parameters of another functions)

[3.0.1] 17.08.2020

• 🛠 [Fixed] Solve issue #26, support export { variables as var } statement.
• ✔ [Added] now interface SvelteDataItem provides a new property localName with information about internal name of component property.

[3.0.0] 08.08.2020

• 🛠 [Fixed] Solve vulnerability issues:
  • Update espree to 7.2.0
  • Update htmlparser2 to 3.9.2
  • Add dependency to eslint to fix issues after upgrading to new versions
• 🔥 [Breaking] Increase requirement of Node.js to 10.0.0, Node.js v8 now is not supported, this is related with security isssues above. Please let me know if it still required.

Full changelog of release versions can be found here

Install

npm install --save sveltedoc-parser

Features

• JSDoc support
  • Support description extraction for everything items
  • Support visibility scope from JSDoc keywords: @public, @protected, @private
• Extract global component description and keywords from JSDoc comment (Svelte 3)
  • Top level comment must include @component. Example script, Example html
• Extract list of imported components
  • Extract relative path to imported component (supports full-syntax and short-syntax import styles)
• Extract data properties
  • Extract description from JSDoc comment
  • Extract JS type from JSDoc (@type {string}) or parse default value if is not provided
• Extract computed properties with list of dependencies
• Extract list of references that attached to components or HTML elements
• Extract information about events
  • Events that propagated from child component or HTML elements <button on:click>...</button>
  • Parse event modifiers ... on:click|once
• Extract all fired events (Svelte 2 only)
  • Events that fired by this component by fire(...) method
  • Custom event handlers with private visibility scope
• Extract all dispatched events (Svelte 3)
  • Events that dispatched from script block by user-created dispatcher
  • Events that dispatched from markup expressions by user-created dispatcher
• Extract list of used default and named slots
• Extract component methods
  • Extract description from JSDoc comment
  • Extract parameters description from JSDoc comment
  • Extract JS type from JSDoc for parameters (@param {string} parameter)
  • Identify optional parameters (@param [parameter]), Google Closure Compiler syntax supported as well (@param {string=} parameter)
  • Identify default values for optional parameters (@param [parameter=Default value])
• Extract component helpers (Svelte 2 only)
• Extract component actions (Svelte 2 only)
• Extract component transitions (Svelte 2 only)
• Extract source locations for component symbols
  • data
  • slots
  • methods
  • refs
  • events

Configuration

json Path	Description	Default value
filename	The filename to parse. Required, unless fileContent is passed.
fileContent	The file content to parse. Required, unless filename is passed.
encoding	The file encoding.	utf8
features	The component features to parse and extracting.	By default used all supported features (see below).
ignoredVisibilities	The list of ignored visibilities.	['private', 'protected']
includeSourceLocations	Flag, which indicates that source locations should be provided for component symbols.	false
version	Optional. Use 2 or 3 to specify which svelte syntax should be used. When that is not provided, parser try to detect version of the syntax.	undefined
defaultVersion	Optional. Specify default version of svelte syntax, if auto-detector can't identify correct version.	undefined

Supported feature names

• 'name' - Extract the component name (Supported by Svelte 2 and Svelte 3).
• 'data' - Extract and parse the list of component data properties (Supported by Svelte 2 and Svelte 3).
• 'computed' - Extract and parse the list of component computed properties (Supported by Svelte 2 and Svelte 3).
• 'methods' - Extract the list of component methods (Supported by Svelte 2 and Svelte 3).
• 'actions' - Extract the list of component actions (Supported by Svelte 2).
• 'helpers' - Extract the list of component helpers (Supported by Svelte 2).
• 'components' - Extract the list of imported components (Supported by Svelte 2 and Svelte 3).
• 'description' - Extract the component description (Supported by Svelte 2 and Svelte 3).
• 'keywords' - Extract the component keywords (Supported by Svelte 2 and Svelte 3).
• 'events' - Extract the list of events that fired by this component (Supported by Svelte 2 and Svelte 3).
• 'slots' - Extract the list of slots provided by this component (Supported by Svelte 2 and Svelte 3).
• 'transitions' - Extract the list of transitions used by this component (Supported by Svelte 2).
• 'refs' - Extract the list of references used by this component (Supported by Svelte 2 and Svelte 3).

Output format

Output format are described at this document.

Please follow to Examples folder to check how Svelte components transforms to JSON document.

See example of output for Svelte 2 component here presented in JSON format for this component.

Usage

const sveltedoc = require('sveltedoc-parser');
const options = {
    filename: 'main.svelte'
};

sveltedoc.parse(options)
    .then(componentDoc => {
        console.log(componentDoc);
    })
    .catch(e => {
        console.error(e);
    });

API

parse(options)

Method to parse svelte component and provide doc object structure with details information.

detectVersion(options)

Method to detect svelte syntax version

• Returns 3 when Svelte 3 special syntax feature are used
• Returns 2 when Svelte 2 special syntax feature are used
• Returns defaultVersion or undefined when specific version can't be identified

Issues

All list of known issues presented at this page.

Found a new issues? Please contribute and write detailed description here.

Contributors

Author Alexey Mulyukin

Based on vuedoc-parse

License

MIT

Changelog

[3.0.4] 25.08.2020

• 🛠 [Fixed] Fix issue #5 (slots items have a private access level by default)