runtypex 0.2.0 → 0.2.1

package/README.md

@@ -79,6 +79,7 @@ interface UserDto {
 }
 
 interface User {
+  /** User id */
   id: string;
   displayName: string;
   isActive: boolean;
@@ -87,7 +88,6 @@ interface User {
 const userMap = defineMap<UserDto, User>()({
   id: source("user_id", {
     db: "users.user_id",
-    description: "User id",
     dtoDescription: "User identifier from the user DTO.",
   }),
   displayName: source("profile.name"),

package/dist/cjs/core/emitMapperFromSpec.d.ts

@@ -9,6 +9,7 @@ export type MapRuleInfo = {
     key: string;
     from: string;
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
 };

package/dist/cjs/generator/generate-jsdoc.js

@@ -7,6 +7,7 @@ exports.generateJSDocFromSpec = generateJSDocFromSpec;
 const typescript_1 = __importDefault(require("typescript"));
 const path_js_1 = require("../core/path.js");
 const emitMapperFromSpec_js_1 = require("../core/emitMapperFromSpec.js");
+const JSDOC_CONTENT_WIDTH = 76;
 function generateJSDocFromSpec(params) {
     const checker = params.checker;
     const dtoName = params.dtoType.symbol?.name ?? "Dto";
@@ -22,18 +23,21 @@ function generateJSDocFromSpec(params) {
         const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
         const domainType = declaration ? checker.getTypeOfSymbolAtLocation(prop, declaration) : checker.getAnyType();
         const dtoPathType = _getTypeAtPath(checker, params.dtoType, rule.from);
+        const description = _getDomainDescription(checker, prop) ?? rule.description;
         const optional = (prop.getFlags() & typescript_1.default.SymbolFlags.Optional) !== 0 ? "?" : "";
         lines.push("  /**");
-        if (rule.description) {
-            lines.push(`   * ${_escapeComment(rule.description)}`);
+        if (description) {
+            _pushJSDocText(lines, _escapeComment(description));
             lines.push("   *");
         }
-        const dtoDescription = rule.dtoDescription ? ` ${_escapeComment(rule.dtoDescription)}` : "";
-        lines.push(`   * DTO: ${dtoName}.${rule.from}${dtoDescription}`);
-        lines.push(`   * DTO type: ${dtoPathType ? checker.typeToString(dtoPathType) : "unknown"}`);
+        _pushJSDocField(lines, "DTO", `${dtoName}.${rule.from}`);
+        if (rule.dtoDescription) {
+            _pushJSDocText(lines, _escapeComment(rule.dtoDescription), "     ");
+        }
+        _pushJSDocField(lines, "DTO type", dtoPathType ? checker.typeToString(dtoPathType) : "unknown");
         if (rule.db)
-            lines.push(`   * DB: ${_escapeComment(rule.db)}`);
-        lines.push(`   * Domain type: ${checker.typeToString(domainType)}`);
+            _pushJSDocField(lines, "DB", _escapeComment(rule.db));
+        _pushJSDocField(lines, "Domain type", checker.typeToString(domainType));
         lines.push("   */");
         lines.push(`  ${_propertyName(prop.name)}${optional}: ${checker.typeToString(domainType)};`);
         lines.push("");
@@ -67,3 +71,33 @@ function _propertyName(name) {
 function _escapeComment(value) {
     return value.replace(/\*\//g, "* /");
 }
+function _getDomainDescription(checker, prop) {
+    const description = typescript_1.default.displayPartsToString(prop.getDocumentationComment(checker)).trim();
+    return description || null;
+}
+function _pushJSDocField(lines, label, value) {
+    _pushJSDocText(lines, `${label}: ${value}`, "", " ".repeat(label.length + 2));
+}
+function _pushJSDocText(lines, text, firstIndent = "", continuationIndent = firstIndent) {
+    for (const line of _wrapJSDocText(text, firstIndent, continuationIndent)) {
+        lines.push(`   * ${line}`);
+    }
+}
+function _wrapJSDocText(text, firstIndent, continuationIndent) {
+    const words = text.replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+    if (!words.length)
+        return [firstIndent.trimEnd()];
+    const lines = [];
+    let current = firstIndent;
+    for (const word of words) {
+        const candidate = current.trim().length ? `${current} ${word}` : `${current}${word}`;
+        if (candidate.length <= JSDOC_CONTENT_WIDTH || !current.trim().length) {
+            current = candidate;
+            continue;
+        }
+        lines.push(current.trimEnd());
+        current = `${continuationIndent}${word}`;
+    }
+    lines.push(current.trimEnd());
+    return lines;
+}

package/dist/cjs/runtime/mapper.d.ts

@@ -5,6 +5,7 @@ export type PathOf<T> = T extends Primitive ? never : T extends readonly (infer
 export type Mapper<TDto, TDomain> = (dto: TDto) => TDomain;
 export type MapperMetadata<TValue = never> = {
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
     default?: TValue;

package/dist/esm/core/emitMapperFromSpec.d.ts

@@ -9,6 +9,7 @@ export type MapRuleInfo = {
     key: string;
     from: string;
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
 };

package/dist/esm/generator/generate-jsdoc.js

@@ -1,6 +1,7 @@
 import ts from "typescript";
 import { parsePath } from "../core/path.js";
 import { findMapPolicyViolations, handleMapPolicyViolations, readMapRules } from "../core/emitMapperFromSpec.js";
+const JSDOC_CONTENT_WIDTH = 76;
 export function generateJSDocFromSpec(params) {
     const checker = params.checker;
     const dtoName = params.dtoType.symbol?.name ?? "Dto";
@@ -16,18 +17,21 @@ export function generateJSDocFromSpec(params) {
         const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
         const domainType = declaration ? checker.getTypeOfSymbolAtLocation(prop, declaration) : checker.getAnyType();
         const dtoPathType = _getTypeAtPath(checker, params.dtoType, rule.from);
+        const description = _getDomainDescription(checker, prop) ?? rule.description;
         const optional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0 ? "?" : "";
         lines.push("  /**");
-        if (rule.description) {
-            lines.push(`   * ${_escapeComment(rule.description)}`);
+        if (description) {
+            _pushJSDocText(lines, _escapeComment(description));
             lines.push("   *");
         }
-        const dtoDescription = rule.dtoDescription ? ` ${_escapeComment(rule.dtoDescription)}` : "";
-        lines.push(`   * DTO: ${dtoName}.${rule.from}${dtoDescription}`);
-        lines.push(`   * DTO type: ${dtoPathType ? checker.typeToString(dtoPathType) : "unknown"}`);
+        _pushJSDocField(lines, "DTO", `${dtoName}.${rule.from}`);
+        if (rule.dtoDescription) {
+            _pushJSDocText(lines, _escapeComment(rule.dtoDescription), "     ");
+        }
+        _pushJSDocField(lines, "DTO type", dtoPathType ? checker.typeToString(dtoPathType) : "unknown");
         if (rule.db)
-            lines.push(`   * DB: ${_escapeComment(rule.db)}`);
-        lines.push(`   * Domain type: ${checker.typeToString(domainType)}`);
+            _pushJSDocField(lines, "DB", _escapeComment(rule.db));
+        _pushJSDocField(lines, "Domain type", checker.typeToString(domainType));
         lines.push("   */");
         lines.push(`  ${_propertyName(prop.name)}${optional}: ${checker.typeToString(domainType)};`);
         lines.push("");
@@ -61,3 +65,33 @@ function _propertyName(name) {
 function _escapeComment(value) {
     return value.replace(/\*\//g, "* /");
 }
+function _getDomainDescription(checker, prop) {
+    const description = ts.displayPartsToString(prop.getDocumentationComment(checker)).trim();
+    return description || null;
+}
+function _pushJSDocField(lines, label, value) {
+    _pushJSDocText(lines, `${label}: ${value}`, "", " ".repeat(label.length + 2));
+}
+function _pushJSDocText(lines, text, firstIndent = "", continuationIndent = firstIndent) {
+    for (const line of _wrapJSDocText(text, firstIndent, continuationIndent)) {
+        lines.push(`   * ${line}`);
+    }
+}
+function _wrapJSDocText(text, firstIndent, continuationIndent) {
+    const words = text.replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+    if (!words.length)
+        return [firstIndent.trimEnd()];
+    const lines = [];
+    let current = firstIndent;
+    for (const word of words) {
+        const candidate = current.trim().length ? `${current} ${word}` : `${current}${word}`;
+        if (candidate.length <= JSDOC_CONTENT_WIDTH || !current.trim().length) {
+            current = candidate;
+            continue;
+        }
+        lines.push(current.trimEnd());
+        current = `${continuationIndent}${word}`;
+    }
+    lines.push(current.trimEnd());
+    return lines;
+}

package/dist/esm/runtime/mapper.d.ts

@@ -5,6 +5,7 @@ export type PathOf<T> = T extends Primitive ? never : T extends readonly (infer
 export type Mapper<TDto, TDomain> = (dto: TDto) => TDomain;
 export type MapperMetadata<TValue = never> = {
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
     default?: TValue;

package/docs/jsdoc-generation.md

@@ -20,14 +20,22 @@ const source = generateJSDocFromSpec({
 This API is intended for build tooling that already has access to the TypeScript
 program, checker, DTO type, domain type, and mapper spec node.
 
-## Metadata Fields
+## Metadata Sources
 
-Mapper metadata can include:
+Domain field descriptions should live on the domain type:
+
+```ts
+interface User {
+  /** User id */
+  id: string;
+}
+```
+
+Mapper metadata can include source-specific details:
 
 ```ts
 source("user_id", {
   db: "users.user_id",
-  description: "User id",
   dtoDescription: "Identifier returned by the user API.",
 });
 ```
@@ -36,18 +44,26 @@ Field meanings:
 
 | Field | Meaning |
 | --- | --- |
-| `description` | Domain field description. Usually used as the first JSDoc sentence. |
-| `dtoDescription` | Optional explanation attached to the DTO path line. |
+| Domain property JSDoc | Domain field description. Usually used as the first JSDoc sentence. |
+| `dtoDescription` | Optional explanation shown below the DTO path line. |
 | `db` | Optional database table and column reference. |
 
+For older mapper specs, `description` is still read as a fallback when the
+domain property has no JSDoc. New code should prefer domain property JSDoc so
+the domain description is not duplicated per DTO mapping.
+
 ## Generated Output
 
-Given this domain field:
+Given this domain field and mapping:
 
 ```ts
+interface User {
+  /** User id */
+  id: string;
+}
+
 id: source("user_id", {
   db: "users.user_id",
-  description: "User id",
   dtoDescription: "Identifier returned by the user API.",
 });
 ```
@@ -58,7 +74,8 @@ the generated documentation can look like this:
 /**
  * User id
  *
- * DTO: UserDto.user_id Identifier returned by the user API.
+ * DTO: UserDto.user_id
+ *      Identifier returned by the user API.
  * DTO type: string
  * DB: users.user_id
  * Domain type: string

package/docs/mapper.md

@@ -77,13 +77,13 @@ Mapping rules can include metadata:
 ```ts
 id: source("user_id", {
   db: "users.user_id",
-  description: "User id",
   dtoDescription: "Identifier returned by the user API.",
 });
 ```
 
 Metadata is not required for mapping. It is mainly used by JSDoc generation and
-documentation tooling.
+documentation tooling. Keep domain field descriptions on the domain type JSDoc;
+mapper metadata should describe DTO/database-specific details.
 
 ## Typed Helpers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runtypex",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Runtime type guards compiled from TypeScript types.",
   "license": "MIT",
   "author": "KumJungMin",