The sveltedoc parser
Generate a JSON documentation for a Svelte file.
Table of Contents
Changelog
[4.2.1] 15.12.2021
-
🛠 [Fixed] - Add missed dependency.
[4.2.0] 14.12.2021
-
🔒 [Fixed] Upgrade all dependecies to latest version to solve known vulnarability issues. -
✔ [Added] Add support ES6 default value assignment for method parameter Issue #75. Thanks for @ekhaled. -
✔ [Added] Add support of method parsing when it assigned to identifier Issue #78. Thanks for @ekhaled. -
✔ [Added] Extend typings to supportself
andtrusted
event modifiers [Issue #80]. -
✔ [Added] IntroduceJSDocTypeFunction
to support functions types in variable definitions and provide details about function parameters and methods. -
✔ [Added] ExtendJSDocType
to support newJSDocTypeFunction
. -
✔ [Added] Improve type infering from assigned value. Currently support simple infering:array
,object
,function
. -
🛠 [Fixed] Fix the Issue #67, Issue #69: specifier comments are not parsed properly; Thanks to @ekhaled. -
🛠 [Fixed] Fix the Issue #72: Module context scripts look for the wrong attribute. -
🛠 [Fixed] Fix the Issue #83: Default value and keywords of exported aliases not merged.
[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 fieldimportPath
introduced toJSDocType
, 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 totypings.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 theSvelteSlotParameter
definition, to supportname
,description
,type
fields, instead of many not relevant fields that was inherited fromISvelteItem
interface. -
🔥 [Breaking] Spec: change theSvelteSlotItem
definition, to improve consistency:- Rename
parameters
property toparams
to be most likely the same asSvelteMethodItem
. Old field still available until 5.* release.
- Rename
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 toparams
; - Change the structure of
return
item for methods:-
desc
property renamed todescription
; -
type
property now contains aJSDocType
object instead of astring
with a text representation of the type. This text representation is still available from thetext
property of theJSDocType
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: Uselocations
instead; -
value
property ofSvelteComponentItem
removed: UseimportPath
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
- Events that propagated from child component or HTML elements
- 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]
)
- Identify default values for optional parameters (
- 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
- Events fired by this component using the
- 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
- Top level comment must include
- 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
or3
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