sveld 0.24.3 → 0.24.5

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/create-exports.js

@@ -16,33 +16,55 @@ function createExports(parsed_exports) {
     const exportStatements = [];
     for (const [source, exports] of groupedBySource) {
         const isSvelteFile = SVELTE_EXT_REGEX.test(source);
+        // Check if this source has both default and non-default exports (indicates module context exports)
+        // Exclude id="default" from this check, as that's just re-exporting the default as-is
+        const hasDefaultExport = exports.some(({ id, exportee }) => id !== "default" && exportee.default);
+        const hasNonDefaultExport = exports.some(({ exportee }) => !exportee.default);
+        const hasMixedExports = isSvelteFile && hasDefaultExport && hasNonDefaultExport;
         // Separate named exports from default exports
         const namedExports = [];
         const defaultExports = [];
+        const defaultAsExports = []; // Track "default as X" exports
         for (const { id, exportee } of exports) {
             // If id is "default", always export as default
             if (id === "default") {
                 defaultExports.push(`export { default } from "${source}";`);
                 continue;
             }
-            // If exportee.default is true, OR if it's a Svelte component, we're re-exporting a default export with a new name
-            if (exportee.default || isSvelteFile) {
+            // If exportee.default is true, we're re-exporting a default export with a new name
+            if (exportee.default) {
                 if (exportee.mixed) {
                     defaultExports.push(`export { default as ${id} } from "${source}";`);
                     defaultExports.push(`export { default } from "${source}";`);
                 }
                 else {
-                    defaultExports.push(`export { default as ${id} } from "${source}";`);
+                    // Use "default as X" so they can be grouped with named exports from same source
+                    defaultAsExports.push(`default as ${id}`);
                 }
             }
+            else if (isSvelteFile && !hasMixedExports) {
+                // For Svelte files without mixed exports, treat as component (re-export default)
+                defaultAsExports.push(`default as ${id}`);
+            }
             else {
-                // It's a named export
+                // It's a named export (including named exports from Svelte module context)
                 namedExports.push(id);
             }
         }
-        // Generate grouped named exports
-        if (namedExports.length > 0) {
-            exportStatements.push(`export { ${namedExports.join(", ")} } from "${source}";`);
+        // Combine default-as-renamed and named exports from same source (for Svelte module exports)
+        if (defaultAsExports.length > 0 && namedExports.length > 0) {
+            // Combine into single statement: export { default as X, namedExport } from "source"
+            exportStatements.push(`export { ${[...defaultAsExports, ...namedExports].join(", ")} } from "${source}";`);
+        }
+        else {
+            // Generate grouped named exports
+            if (namedExports.length > 0) {
+                exportStatements.push(`export { ${namedExports.join(", ")} } from "${source}";`);
+            }
+            // Add default-as exports
+            if (defaultAsExports.length > 0) {
+                exportStatements.push(`export { ${defaultAsExports.join(", ")} } from "${source}";`);
+            }
         }
         // Add default exports (these cannot be grouped)
         exportStatements.push(...defaultExports);

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");
 }
@@ -356,7 +382,7 @@ function genModuleExports(def) {
         }
         else if (prop.kind === "const") {
             // For const exports from script context="module", use declare const instead of type
-            type_def = `export declare const ${prop.name}: ${prop.type || ANY_TYPE};`;
+            type_def = `export declare const ${prop.name}: ${prop.type || ANY_TYPE};\n`;
         }
         return `
       ${prop_comments.length > 0 ? `/**\n${prop_comments}*/` : EMPTY_STR}

package/package.json

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