The sveltedoc parser

Generate a JSON documentation for a Svelte file.

Table of Contents

• Changelog
  • [4.1.0] 19.02.2021
  • [4.0.0] 25.01.2021
• Install
• Features
  • Common
  • Svelte 2
  • Svelte 3
• Options
  • Supported feature names
• Output format
• Usage
• API
  • parse(options)
  • detectVersion(options)
• Issues
• Contributors
• License

Changelog

[4.1.0] 19.02.2021

• 🎉 [Misc] Update the ReadMe by @soft-decay.
• ✔ [Added] Implement support of imported types parsing, f.ex. @type {import('../typings.d.ts').ExternalTypeClass}. In order to do this, new field importPath introduced to JSDocType, in the name property now it returns imported class name, f.ex.: ExternalTypeClass.
• 🛠 [Fixed] Complete fix of Issue #1: Support parsing event names from top-level constant objects with accessing to their properties by naming strings. Introduce the new issue Issue #48 about supporting parse of event names by external references.
• 🛠 [Fixed] Fix the Issue #47, now all comments in markup are parsed correctly and attached to required items in document. Support JSDoc comment markup parsing in all places where comment can be used.
• 🛠 [Fixed] Fix the Issue #61, now slot parameter items enrich with all detailed information that was parsed from markup comment.
• 🛠 [Fixed] Spec: add the module definition typings to typings.d.ts file.
• 🛠 [Fixed] Fix some edge-cases in script parsing logic.
• 🛠 [Tech] Refactor internal parser logic to make it easy to introduce new features, moves forward to TS support! ;)
• 🔥 [Breaking] Spec: change the SvelteSlotParameter definition, to support name, description, type fields, instead of many not relevant fields that was inherited from ISvelteItem interface.
• 🔥 [Breaking] Spec: change the SvelteSlotItem definition, to improve consistency:
  • Rename parameters property to params to be most likely the same as SvelteMethodItem. Old field still available until 5.* release.

Thanks a lot @soft-decay for contributing in this release!

[4.0.0] 25.01.2021

• 🛠 [Fixed] Fix Issue #42
• 🛠 [Fixed] Partially fixed Issue #1. Event names are now correctly parsed if provided by a top-level constant in the same file. Thanks to @soft-decay
• ✔ [Added] Support complete parsing of component method arguments Issue #39. Thanks to @soft-decay
• ✔ [Added] Support parsing of return type and description for methods in component Issue #37. Thanks to @soft-decay
• ✔ [Added] Options validation, Thanks to @soft-decay
• 🔥 [Breaking] API rework for component methods description:
  • args property renamed to params;
  • Change the structure of return item for methods:
    • desc property renamed to description;
    • type property now contains a JSDocType object instead of a string with a text representation of the type. This text representation is still available from the text property of the JSDocType object;
  • [Svelte2]: method arguments presented with plain array with names, now that replaced with objects of SvelteMethodParamItem type;
• 🔥 [Breaking] Cleanup deprecated code:
  • loc property removed: Use locations instead;
  • value property of SvelteComponentItem removed: Use importPath instead;

Full changelog of release versions can be found here.

Install

npm install --save sveltedoc-parser

Features

Common

• JSDoc support
  • Support description extraction for everything items
  • Support visibility scope from JSDoc keywords: @public, @protected, @private
• 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 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 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 using brackets (@param [parameter]) or using Google ClosureCompiler syntax (@param {string=} parameter)
    • Identify default values for optional parameters (@param [parameter=Default value])
• Extract source locations for component symbols
  • data (props)
  • slots
  • methods
  • refs
  • events

Svelte 2

• Extract fired events
  • Events fired by this component using the fire(...) method
  • Custom event handlers with private visibility scope
• Extract component helpers
• Extract component actions
• Extract component transitions

Svelte 3

• Extract global component description and keywords from JSDoc comment
  • Top level comment must include @component. Example script, Example html
• Extract all dispatched events
  • Events that dispatched from script block by user-created dispatcher
  • Events that dispatched from markup expressions by user-created dispatcher

Options

The options object passed to the parse function must include filename or fileContent.

Here are the properties supported by options (see the Usage section below):

json Path	Description	Type	Default value
filename	The filename to parse. Required, unless fileContent is passed.	string
fileContent	The file content to parse. Required, unless filename is passed.	string
encoding	The file encoding.	string	utf8
features	The component features to parse and extract.	string[]	All supported features
ignoredVisibilities	The list of ignored visibilities. Symbols with a visibility that is ignored will not be included in the output.	string[]	['private', 'protected']
includeSourceLocations	Flag, which indicates that source locations should be provided for component symbols.	boolean	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.	number?	undefined
defaultVersion	Optional. Specify default version of svelte syntax, if auto-detector can't identify correct version.	number?	undefined

Supported feature names

These are the values that can be included in the options.features array:

Feature	Svelte 2	Svelte 3	Description
name	✔	✔	Component's name
description	✔	✔	Component's description
keywords	✔	✔	List of JSDoc keywords found in the top level comment
components	✔	✔	List of imported components
computed	✔	✔	List of computed properties
data	✔	✔	List of data properties (Component's props)
events	✔	✔	List of events fired/dispatched by this component
methods	✔	✔	List of methods
refs	✔	✔	List of references used by this component
slots	✔	✔	List of slots provided by this component
actions	✔		List of actions
helpers	✔		List of helpers
transitions	✔		List of transitions used by this component
store			NOT SUPPORTED

Output format

Output format is described in this document.

For Svelte 3 examples, take a look at the examples folder to check how Svelte 3 components are transformed to JSON documents.

For a Svelte 2 example, take a look at the JSON output generated from this component.

Usage

Minimal example:

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

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

or with options customization:

const { parse } = require('sveltedoc-parser');
const { externalFileContent } = require('./local-file');
const options = {
    fileContent: externalFileContent,
    encoding: 'ascii',
    features: ['data', 'computed', 'methods'],
    ignoredVisibilities: ['private'],
    includeSourceLocations: true,
    version: 3
};
const doc = await parse(options);
console.log(doc)

API

parse(options)

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

detectVersion(options)

Method to detect the Svelte syntax used in the component. It returns, in order:

• the value of options.version, if present; else
• 2 or 3 if Svelte 2 syntax or Svelte 3 syntax is detected, respectively; else
• the value of options.defaultVersion, if present; else
• undefined if the function failed to detect the syntax to use

Issues

A list of known issues can be found here.

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

Contributors

Author Alexey Mulyukin

Inspired by Vuedoc Parser

License

MIT