{"id":18031448,"url":"https://github.com/katchaotic/sveltedoc-parser","last_synced_at":"2025-04-06T08:15:49.056Z","repository":{"id":41203261,"uuid":"155226896","full_name":"KatChaotic/sveltedoc-parser","owner":"KatChaotic","description":"Generate a JSON documentation for a Svelte (https://github.com/sveltejs/svelte) component","archived":false,"fork":false,"pushed_at":"2024-10-26T11:26:58.000Z","size":478,"stargazers_count":92,"open_issues_count":23,"forks_count":8,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2025-04-06T08:15:38.542Z","etag":null,"topics":["docs","jsdoc","parser","svelte","svelte-documentation","sveltejs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/sveltedoc-parser","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KatChaotic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-29T14:35:26.000Z","updated_at":"2025-02-08T04:44:53.000Z","dependencies_parsed_at":"2024-06-18T13:56:51.610Z","dependency_job_id":"f4c01d0d-2e2a-4166-b061-43b8ad2000c9","html_url":"https://github.com/KatChaotic/sveltedoc-parser","commit_stats":{"total_commits":187,"total_committers":9,"mean_commits":20.77777777777778,"dds":0.6737967914438503,"last_synced_commit":"7b7d0ff777731ce8ed35ddead97eaa85afe9e82f"},"previous_names":["katchaotic/sveltedoc-parser","alexprey/sveltedoc-parser"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatChaotic%2Fsveltedoc-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatChaotic%2Fsveltedoc-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatChaotic%2Fsveltedoc-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatChaotic%2Fsveltedoc-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KatChaotic","download_url":"https://codeload.github.com/KatChaotic/sveltedoc-parser/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247451666,"owners_count":20940944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","jsdoc","parser","svelte","svelte-documentation","sveltejs"],"created_at":"2024-10-30T10:06:30.615Z","updated_at":"2025-04-06T08:15:49.028Z","avatar_url":"https://github.com/KatChaotic.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The sveltedoc parser \u003c!-- omit in toc --\u003e\r\n\r\nGenerate a JSON documentation for a Svelte file.\r\n\r\n[![npm](https://img.shields.io/npm/v/sveltedoc-parser.svg)](https://www.npmjs.com/package/sveltedoc-parser)\r\n![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/alexprey/sveltedoc-parser/Node%20CI/master)\r\n\r\n## Table of Contents \u003c!-- omit in toc --\u003e\r\n\r\n- [Changelog](#changelog)\r\n  - [[4.2.1] 15.12.2021](#421-15122021)\r\n  - [[4.2.0] 14.12.2021](#420-14122021)\r\n  - [[4.1.0] 19.02.2021](#410-19022021)\r\n  - [[4.0.0] 25.01.2021](#400-25012021)\r\n- [Install](#install)\r\n- [Features](#features)\r\n  - [Common](#common)\r\n  - [Svelte 2](#svelte-2)\r\n  - [Svelte 3](#svelte-3)\r\n- [Options](#options)\r\n  - [Supported feature names](#supported-feature-names)\r\n- [Output format](#output-format)\r\n- [Usage](#usage)\r\n- [API](#api)\r\n  - [parse(options)](#parseoptions)\r\n  - [detectVersion(options)](#detectversionoptions)\r\n- [Issues](#issues)\r\n- [Contributors](#contributors)\r\n- [License](#license)\r\n\r\n## Changelog\r\n\r\n### [4.2.1] 15.12.2021\r\n- 🛠 **[Fixed]** - Add missed dependency.\r\n\r\n### [4.2.0] 14.12.2021\r\n\r\n- 🔒 **[Fixed]** Upgrade all dependecies to latest version to solve known vulnarability issues.\r\n- ✔ **[Added]** Add support ES6 default value assignment for method parameter [Issue #75](https://github.com/alexprey/sveltedoc-parser/issues/75). Thanks for [@ekhaled](https://github.com/ekhaled).\r\n- ✔ **[Added]** Add support of method parsing when it assigned to identifier [Issue #78](https://github.com/alexprey/sveltedoc-parser/issues/78). Thanks for [@ekhaled](https://github.com/ekhaled).\r\n- ✔ **[Added]** Extend typings to support `self` and `trusted` event modifiers [Issue #80].\r\n- ✔ **[Added]** Introduce `JSDocTypeFunction` to support functions types in variable definitions and provide details about function parameters and methods.\r\n- ✔ **[Added]** Extend `JSDocType` to support new `JSDocTypeFunction`.\r\n- ✔ **[Added]** Improve type infering from assigned value. Currently support simple infering: `array`, `object`, `function`.\r\n- 🛠 **[Fixed]** Fix the [Issue #67](https://github.com/alexprey/sveltedoc-parser/issues/67), [Issue #69](https://github.com/alexprey/sveltedoc-parser/issues/69): specifier comments are not parsed properly; Thanks to [@ekhaled](https://github.com/ekhaled).\r\n- 🛠 **[Fixed]** Fix the [Issue #72](https://github.com/alexprey/sveltedoc-parser/issues/72): Module context scripts look for the wrong attribute.\r\n- 🛠 **[Fixed]** Fix the [Issue #83](https://github.com/alexprey/sveltedoc-parser/issues/83): Default value and keywords of exported aliases not merged.\r\n\r\n### [4.1.0] 19.02.2021\r\n\r\n- 🎉 **[Misc]** Update the ReadMe by [@soft-decay](https://github.com/soft-decay).\r\n- ✔ **[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`.\r\n- 🛠 **[Fixed]** Complete fix of [Issue #1](https://github.com/alexprey/sveltedoc-parser/issues/1): Support parsing event names from top-level constant objects with accessing to their properties by naming strings. Introduce the new issue [Issue #48](https://github.com/alexprey/sveltedoc-parser/issues/48) about supporting parse of event names by external references.\r\n- 🛠 **[Fixed]** Fix the [Issue #47](https://github.com/alexprey/sveltedoc-parser/issues/48), 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.\r\n- 🛠 **[Fixed]** Fix the [Issue #61](https://github.com/alexprey/sveltedoc-parser/issues/61), now slot parameter items enrich with all detailed information that was parsed from markup comment.\r\n- 🛠 **[Fixed]** Spec: add the module definition typings to `typings.d.ts` file.\r\n- 🛠 **[Fixed]** Fix some edge-cases in script parsing logic.\r\n- 🛠 **[Tech]** Refactor internal parser logic to make it easy to introduce new features, moves forward to TS support! ;)\r\n- 🔥 **[Breaking]** Spec: change the `SvelteSlotParameter` definition, to support `name`, `description`, `type` fields, instead of many not relevant fields that was inherited from `ISvelteItem` interface.\r\n- 🔥 **[Breaking]** Spec: change the `SvelteSlotItem` definition, to improve consistency:\r\n  - Rename `parameters` property to `params` to be most likely the same as `SvelteMethodItem`. Old field still available until 5.* release.\r\n\r\nThanks a lot [@soft-decay](https://github.com/soft-decay) for contributing in this release!\r\n\r\n### [4.0.0] 25.01.2021\r\n\r\n- 🛠 **[Fixed]** Fix [Issue #42](https://github.com/alexprey/sveltedoc-parser/issues/42)\r\n- 🛠 **[Fixed]** Partially fixed [Issue #1](https://github.com/alexprey/sveltedoc-parser/issues/1). Event names are now correctly parsed if provided by a top-level constant in the same file. Thanks to [@soft-decay](https://github.com/soft-decay)\r\n- ✔ **[Added]** Support complete parsing of component method arguments [Issue #39](https://github.com/alexprey/sveltedoc-parser/issues/39). Thanks to [@soft-decay](https://github.com/soft-decay)\r\n- ✔ **[Added]** Support parsing of return type and description for methods in component [Issue #37](https://github.com/alexprey/sveltedoc-parser/issues/37). Thanks to [@soft-decay](https://github.com/soft-decay)\r\n- ✔ **[Added]** Options validation, Thanks to [@soft-decay](https://github.com/soft-decay)\r\n- 🔥 **[Breaking]** API rework for component methods description:\r\n  - `args` property renamed to `params`;\r\n  - Change the structure of `return` item for methods:\r\n    - `desc` property renamed to `description`;\r\n    - `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;\r\n  - [Svelte2]: method arguments presented with plain array with names, now that replaced with objects of `SvelteMethodParamItem` type;\r\n- 🔥 **[Breaking]** Cleanup deprecated code:\r\n  - `loc` property removed: Use `locations` instead;\r\n  - `value` property of `SvelteComponentItem` removed: Use `importPath` instead;\r\n\r\nFull changelog of release versions can be found [here](/CHANGELOG.md).\r\n\r\n## Install\r\n\r\n```shell\r\nnpm install --save sveltedoc-parser\r\n```\r\n\r\n## Features\r\n\r\n### Common\r\n\r\n- JSDoc support\r\n  - Support description extraction for everything items\r\n  - Support visibility scope from JSDoc keywords: `@public`, `@protected`, `@private`\r\n- Extract list of imported components\r\n  - Extract relative path to imported component (supports full-syntax and short-syntax import styles)\r\n- Extract data properties\r\n  - Extract description from JSDoc comment\r\n  - Extract JS type from JSDoc (`@type {string}`) or parse default value if is not provided\r\n- Extract computed properties with list of dependencies\r\n- Extract list of references attached to components or HTML elements\r\n- Extract information about events\r\n  - Events that propagated from child component or HTML elements `\u003cbutton on:click\u003e...\u003c/button\u003e`\r\n  - Parse event modifiers `... on:click|once`\r\n- Extract list of used default and named `slots`\r\n- Extract component methods\r\n  - Extract description from JSDoc comment\r\n  - Extract parameters description from JSDoc comment\r\n  - Extract JS type from JSDoc for parameters (`@param {string} parameter`)\r\n  - Identify optional parameters using brackets (`@param [parameter]`) or using Google ClosureCompiler syntax (`@param {string=} parameter`)\r\n    - Identify default values for optional parameters (`@param [parameter=Default value]`)\r\n- Extract source locations for component symbols\r\n  - data (props)\r\n  - slots\r\n  - methods\r\n  - refs\r\n  - events\r\n\r\n### Svelte 2\r\n\r\n- Extract fired events\r\n  - Events fired by this component using the `fire(...)` method\r\n  - Custom event handlers with `private` visibility scope\r\n- Extract component helpers\r\n- Extract component actions\r\n- Extract component transitions\r\n\r\n### Svelte 3\r\n\r\n- Extract global component description and keywords from JSDoc comment\r\n  - Top level comment must include `@component`. [Example script](/test/svelte3/integration/globalComment/globalComment.script.svelte), [Example html](/test/svelte3/integration/globalComment/globalComment.markup.svelte)\r\n- Extract all dispatched events\r\n  - Events that dispatched from script block by user-created dispatcher\r\n  - Events that dispatched from markup expressions by user-created dispatcher\r\n\r\n## Options\r\n\r\nThe `options` object passed to the `parse` function ***must include*** `filename` or `fileContent`.\r\n\r\nHere are the properties supported by `options` (see the [Usage](#Usage) section below):\r\n\r\n| json Path | Description | Type | Default value |\r\n|-----------|-------------|------|---------------|\r\n| **filename** | The filename to parse. **Required**, unless `fileContent` is passed. | string |\r\n| **fileContent** | The file content to parse. **Required**, unless `filename` is passed. | string |\r\n| **encoding** | The file encoding. | string | `utf8` |\r\n| **features** | The component features to parse and extract. | string[] | [All supported features](#Supported-feature-names) |\r\n| **ignoredVisibilities** | The list of ignored visibilities. Symbols with a visibility that is ignored will not be included in the output. | string[] | `['private', 'protected']` |\r\n| **includeSourceLocations** | Flag, which indicates that source locations should be provided for component symbols. | boolean | `false` |\r\n| **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` |\r\n| **defaultVersion** | Optional. Specify default version of svelte syntax, if auto-detector can't identify correct version. | number? | `undefined` |\r\n\r\n### Supported feature names\r\n\r\nThese are the values that can be included in the `options.features` array:\r\n\r\n| Feature       | Svelte 2 | Svelte 3 | Description                                           |\r\n|---------------|:--------:|:--------:|-------------------------------------------------------|\r\n| `name`        |     ✔    |     ✔    | Component's name                                      |\r\n| `description` |     ✔    |     ✔    | Component's description                               |\r\n| `keywords`    |     ✔    |     ✔    | List of JSDoc keywords found in the top level comment |\r\n| `components`  |     ✔    |     ✔    | List of imported components                           |\r\n| `computed`    |     ✔    |     ✔    | List of computed properties                           |\r\n| `data`        |     ✔    |     ✔    | List of data properties (Component's props)           |\r\n| `events`      |     ✔    |     ✔    | List of events fired/dispatched by this component     |\r\n| `methods`     |     ✔    |     ✔    | List of methods                                       |\r\n| `refs`        |     ✔    |     ✔    | List of references used by this component             |\r\n| `slots`       |     ✔    |     ✔    | List of slots provided by this component              |\r\n| `actions`     |     ✔    |          | List of actions                                       |\r\n| `helpers`     |     ✔    |          | List of helpers                                       |\r\n| `transitions` |     ✔    |          | List of transitions used by this component            |\r\n| `store`       |          |          | NOT SUPPORTED                                         |\r\n\r\n## Output format\r\n\r\nOutput format is described in [this document](/typings.d.ts).\r\n\r\nFor Svelte 3 examples, take a look at the [examples folder](/examples/) to check how Svelte 3 components are transformed to JSON documents.\r\n\r\nFor a Svelte 2 example, take a look at the [JSON output](/test/svelte2/integration/overall/overall.main.doc.json) generated from [this component](/test/svelte2/integration/overall/main.svelte).\r\n\r\n## Usage\r\n\r\nMinimal example:\r\n\r\n```js\r\nconst sveltedoc = require('sveltedoc-parser');\r\nconst options = {\r\n    filename: 'main.svelte'\r\n};\r\n\r\nsveltedoc.parse(options)\r\n    .then(componentDoc =\u003e {\r\n        console.log(componentDoc);\r\n    })\r\n    .catch(e =\u003e {\r\n        console.error(e);\r\n    });\r\n```\r\n\r\nor with options customization:\r\n\r\n```js\r\nconst { parse } = require('sveltedoc-parser');\r\nconst { externalFileContent } = require('./local-file');\r\nconst options = {\r\n    fileContent: externalFileContent,\r\n    encoding: 'ascii',\r\n    features: ['data', 'computed', 'methods'],\r\n    ignoredVisibilities: ['private'],\r\n    includeSourceLocations: true,\r\n    version: 3\r\n};\r\nconst doc = await parse(options);\r\nconsole.log(doc)\r\n```\r\n\r\n## API\r\n\r\n### parse(options)\r\n\r\nMethod to parse svelte component and provide doc object structure with details information.\r\n\r\n### detectVersion(options)\r\n\r\nMethod to detect the Svelte syntax used in the component. It returns, in order:\r\n\r\n- the value of `options.version`, if present; else\r\n- `2` or `3` if Svelte 2 syntax or Svelte 3 syntax is detected, respectively; else\r\n- the value of `options.defaultVersion`, if present; else\r\n- `undefined` if the function failed to detect the syntax to use\r\n\r\n## Issues\r\n\r\nA list of known issues can be found [here](https://github.com/alexprey/sveltedoc-parser/issues).\r\n\r\nFound a new issue? Please contribute and write a detailed description [here](https://github.com/alexprey/sveltedoc-parser/issues/new).\r\n\r\n## Contributors\r\n\r\nAuthor [Alexey Mulyukin](https://github.com/alexprey)\r\n\r\nInspired by [Vuedoc Parser](https://gitlab.com/vuedoc/parser)\r\n\r\n## License\r\n\r\n[MIT](/LICENSE)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatchaotic%2Fsveltedoc-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatchaotic%2Fsveltedoc-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatchaotic%2Fsveltedoc-parser/lists"}