sveld 0.24.4 → 0.24.6

package/README.md

@@ -131,6 +131,7 @@ export default class Button extends SvelteComponentTyped<
   - [@extends](#extends)
   - [@generics](#generics)
   - [@component comments](#component-comments)
+  - [Accessor Props](#accessor-props)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -988,6 +989,96 @@ export default class Button extends SvelteComponentTyped<
 > {}
 ```
 
+### Accessor Props
+
+Exported functions and consts become accessor props in generated TypeScript definitions. Use `@type` to document function signatures, or use `@param` and `@returns` (or `@return`) JSDoc tags for richer documentation.
+
+Note that `@type` tag annotations take precedence over `@param`/`@returns` tags.
+
+Signature:
+
+```js
+/**
+ * Function description
+ * @param {Type} paramName - Parameter description
+ * @param {Type} [optionalParam] - Optional parameter
+ * @returns {ReturnType} Return value description
+ */
+```
+
+Example:
+
+```svelte
+<script>
+  /**
+   * @typedef {object} NotificationData
+   * @property {string} [id] - Optional id for deduplication
+   * @property {"error" | "info" | "success"} [kind]
+   */
+
+  /**
+   * Add a notification to the queue.
+   * @param {NotificationData} notification
+   * @returns {string} The notification id
+   */
+  export function add(notification) {
+    const id = notification.id ?? "id";
+    return id;
+  }
+
+  /**
+   * Remove a notification by id.
+   * @param {string} id
+   * @returns {boolean} True if the notification was found and removed
+   */
+  export function remove(id) {
+    return true;
+  }
+
+  /**
+   * Get notification count.
+   * @returns {number} The number of notifications
+   */
+  export function getCount() {
+    return 0;
+  }
+</script>
+```
+
+Output:
+
+```ts
+export type NotificationData = {
+  /** Optional id for deduplication */ id?: string;
+  kind?: "error" | "info" | "success";
+};
+
+export type ComponentProps = Record<string, never>;
+
+export default class Component extends SvelteComponentTyped<
+  ComponentProps,
+  Record<string, any>,
+  Record<string, never>
+> {
+  /**
+   * Add a notification to the queue.
+   */
+  add: (notification: NotificationData) => string;
+
+  /**
+   * Remove a notification by id.
+   */
+  remove: (id: string) => boolean;
+
+  /**
+   * Get notification count.
+   */
+  getCount: () => number;
+}
+```
+
+When only `@param` tags are present without `@returns`, the return type defaults to `any`. When only `@returns` is present without `@param`, the function signature is `() => returnType`.
+
 ## Contributing
 
 Refer to the [contributing guidelines](CONTRIBUTING.md).

package/lib/ComponentParser.d.ts

@@ -19,6 +19,7 @@ interface ComponentProp {
     value?: string;
     description?: string;
     params?: ComponentPropParam[];
+    returnType?: string;
     isFunction: boolean;
     isFunctionDeclaration: boolean;
     isRequired: boolean;

package/lib/ComponentParser.js

@@ -696,6 +696,7 @@ class ComponentParser {
                             isFunctionDeclaration = true;
                         }
                         let params;
+                        let returnType;
                         if (node.leadingComments) {
                             const jsdoc_comment = ComponentParser.findJSDocComment(node.leadingComments);
                             if (jsdoc_comment) {
@@ -718,9 +719,23 @@ class ComponentParser {
                                         optional: tag.optional || false,
                                     }));
                                 }
+                                // Extract @returns/@return tag
+                                const returnsTag = comment[0]?.tags.find((t) => t.tag === "returns" || t.tag === "return");
+                                if (returnsTag)
+                                    returnType = this.aliasType(returnsTag.type);
                                 // Build description from comment description and non-param/non-type tags
                                 const commentDescription = ComponentParser.assignValue(comment[0]?.description?.trim());
-                                const additionalTags = comment[0]?.tags.filter((tag) => !["type", "param", "extends", "restProps", "slot", "event", "typedef"].includes(tag.tag)) ?? [];
+                                const additionalTags = comment[0]?.tags.filter((tag) => ![
+                                    "type",
+                                    "param",
+                                    "returns",
+                                    "return",
+                                    "extends",
+                                    "restProps",
+                                    "slot",
+                                    "event",
+                                    "typedef",
+                                ].includes(tag.tag)) ?? [];
                                 if (commentDescription || additionalTags.length > 0) {
                                     description = commentDescription || "";
                                     for (const tag of additionalTags) {
@@ -739,6 +754,7 @@ class ComponentParser {
                             type,
                             value,
                             params,
+                            returnType,
                             isFunction,
                             isFunctionDeclaration,
                             isRequired: false,
@@ -866,6 +882,7 @@ class ComponentParser {
                         isFunctionDeclaration = true;
                     }
                     let params;
+                    let returnType;
                     if (node.leadingComments) {
                         const jsdoc_comment = ComponentParser.findJSDocComment(node.leadingComments);
                         if (jsdoc_comment) {
@@ -888,9 +905,23 @@ class ComponentParser {
                                     optional: tag.optional || false,
                                 }));
                             }
+                            // Extract @returns/@return tag
+                            const returnsTag = comment[0]?.tags.find((t) => t.tag === "returns" || t.tag === "return");
+                            if (returnsTag)
+                                returnType = this.aliasType(returnsTag.type);
                             // Build description from comment description and non-param/non-type tags
                             const commentDescription = ComponentParser.assignValue(comment[0]?.description?.trim());
-                            const additional_tags = comment[0]?.tags.filter((tag) => !["type", "param", "extends", "restProps", "slot", "event", "typedef"].includes(tag.tag)) ?? [];
+                            const additional_tags = comment[0]?.tags.filter((tag) => ![
+                                "type",
+                                "param",
+                                "returns",
+                                "return",
+                                "extends",
+                                "restProps",
+                                "slot",
+                                "event",
+                                "typedef",
+                            ].includes(tag.tag)) ?? [];
                             if (commentDescription || additional_tags.length > 0) {
                                 description = commentDescription || "";
                                 for (const tag of additional_tags) {
@@ -909,6 +940,7 @@ class ComponentParser {
                         type,
                         value,
                         params,
+                        returnType,
                         isFunction,
                         isFunctionDeclaration,
                         isRequired,

package/lib/writer/writer-ts-definitions-core.js

@@ -320,9 +320,35 @@ function genAccessors(def) {
         const prop_comments = [addCommentLine(prop.description?.replace(NEWLINE_TO_COMMENT_REGEX, "\n* "))]
             .filter(Boolean)
             .join("");
+        // Determine the function signature
+        let functionType;
+        // Check if this is the default function type (would be overridden by @type or params/returns)
+        const isDefaultFunctionType = prop.type === "() => any";
+        // If @type tag provides a custom function signature (contains => and is not the default), use it (highest priority)
+        if (prop.type && FUNCTION_TYPE_REGEX.test(prop.type) && !isDefaultFunctionType) {
+            functionType = prop.type;
+        }
+        else if (prop.params && prop.params.length > 0) {
+            // Build signature from @param tags
+            const paramStrings = prop.params.map((param) => {
+                const optional = param.optional ? "?" : "";
+                return `${param.name}${optional}: ${param.type}`;
+            });
+            const paramsString = paramStrings.join(", ");
+            const returnType = prop.returnType || ANY_TYPE;
+            functionType = `(${paramsString}) => ${returnType}`;
+        }
+        else if (prop.returnType) {
+            // Only @returns is present without @param
+            functionType = `() => ${prop.returnType}`;
+        }
+        else {
+            // Fall back to current prop.type
+            functionType = prop.type || ANY_TYPE;
+        }
         return `
     ${prop_comments.length > 0 ? `/**\n${prop_comments}*/` : EMPTY_STR}
-    ${prop.name}: ${prop.type};`;
+    ${prop.name}: ${functionType};`;
     })
         .join("\n");
 }
@@ -349,7 +375,29 @@ function genModuleExports(def) {
             .join("");
         let type_def = `export type ${prop.name} = ${prop.type || ANY_TYPE};`;
         const is_function = prop.type && FUNCTION_TYPE_REGEX.test(prop.type);
-        if (is_function && prop.type) {
+        const isDefaultFunctionType = prop.type === "() => any";
+        if (is_function && prop.type && !isDefaultFunctionType) {
+            // @type tag provides a custom function signature (highest priority)
+            const [first, second, ...rest] = prop.type.split("=>");
+            const rest_type = rest.map((item) => `=>${item}`).join("");
+            type_def = `export declare function ${prop.name}${first}:${second}${rest_type};`;
+        }
+        else if (prop.params && prop.params.length > 0) {
+            // Build signature from @param tags
+            const paramStrings = prop.params.map((param) => {
+                const optional = param.optional ? "?" : "";
+                return `${param.name}${optional}: ${param.type}`;
+            });
+            const paramsString = paramStrings.join(", ");
+            const returnType = prop.returnType || ANY_TYPE;
+            type_def = `export declare function ${prop.name}(${paramsString}): ${returnType};`;
+        }
+        else if (prop.returnType) {
+            // Only @returns is present without @param
+            type_def = `export declare function ${prop.name}(): ${prop.returnType};`;
+        }
+        else if (is_function && prop.type) {
+            // Fall back to existing function type handling
             const [first, second, ...rest] = prop.type.split("=>");
             const rest_type = rest.map((item) => `=>${item}`).join("");
             type_def = `export declare function ${prop.name}${first}:${second}${rest_type};`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sveld",
-  "version": "0.24.4",
+  "version": "0.24.6",
   "license": "Apache-2.0",
   "description": "Generate TypeScript definitions for your Svelte components.",
   "main": "./lib/index.js",