@amritk/helpers - npm Package Compare versions

Comparing version 0.6.0 to 0.6.1

dist/generate-type-definition.js

@@ -434,2 +434,27 @@ // src/has-ref.ts
         const readonlyPrefix = options.readonly ? "readonly " : "";
+        const hasDescriptions = Object.values(schema.properties).some((p) => isSchemaObject(p) && (typeof p.description === "string" || typeof p.$comment === "string"));
+        if (hasDescriptions) {
+          let properties2 = "";
+          let first2 = true;
+          for (const key in schema.properties) {
+            const propSchema = schema.properties[key];
+            const isRequired = schema.required?.includes(key) ?? false;
+            const optional = isRequired ? "" : "?";
+            const propType = getTypeScriptType(propSchema, options);
+            const inlineDescription = isSchemaObject(propSchema) && typeof propSchema.description === "string" ? propSchema.description : isSchemaObject(propSchema) && typeof propSchema.$comment === "string" ? propSchema.$comment : undefined;
+            if (!first2)
+              properties2 += `
+`;
+            first2 = false;
+            if (inlineDescription) {
+              properties2 += "  /** " + inlineDescription + ` */
+  ` + readonlyPrefix + safeKey(key) + optional + ": " + propType + ";";
+            } else {
+              properties2 += "  " + readonlyPrefix + safeKey(key) + optional + ": " + propType + ";";
+            }
+          }
+          return `{
+` + properties2 + `
+}`;
+        }
         let properties = "";
@@ -476,4 +501,5 @@ let first = true;
     let result = "";
-    if (isSchemaObject(schema) && schema.$comment && typeof schema.$comment === "string") {
-      result += buildJsDocBlock(typeName, schema.$comment);
+    const topLevelComment = isSchemaObject(schema) && typeof schema.description === "string" && schema.description || isSchemaObject(schema) && typeof schema.$comment === "string" && schema.$comment || undefined;
+    if (topLevelComment) {
+      result += buildJsDocBlock(typeName, topLevelComment);
     }
@@ -489,5 +515,6 @@ result += `export type ${typeName} = ${tsType};`;
     let jsDocDescription;
-    if (isSchemaObject(schema) && schema.$comment && typeof schema.$comment === "string") {
+    const topLevelComment = isSchemaObject(schema) && typeof schema.description === "string" && schema.description || isSchemaObject(schema) && typeof schema.$comment === "string" && schema.$comment || undefined;
+    if (topLevelComment) {
       jsDocTitle = typeName;
-      jsDocDescription = schema.$comment;
+      jsDocDescription = topLevelComment;
     }
@@ -494,0 +521,0 @@ const hasProperties2 = normalizedSchema.properties && Object.keys(normalizedSchema.properties).length > 0;

package.json

 {
   "name": "@amritk/helpers",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Shared utilities for the mjst code generation ecosystem.",
@@ -5,0 +5,0 @@ "type": "module",

src/generate-type-definition.test.ts

@@ -879,2 +879,35 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
 
+  it('preserves property descriptions as JSDoc comments when allOf contains an inline object schema', () => {
+    const schema: JSONSchema = {
+      allOf: [
+        { $ref: '#/$defs/baseTargetConfig' },
+        {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            packageName: {
+              type: 'string',
+              description: 'Import/package name for TypeScript and Node packages.',
+            },
+            packageManager: {
+              type: 'string',
+              description: 'TypeScript package manager preference for generated package metadata.',
+            },
+            publish: {
+              $ref: '#/$defs/npmPublishConfig',
+              description: 'npm publishing configuration.',
+            },
+          },
+          required: ['publish'],
+        },
+      ],
+    }
+
+    const result = generateTypeDefinition(schema, 'TypeScriptTargetConfig')
+
+    expect(result).toContain('/** Import/package name for TypeScript and Node packages. */')
+    expect(result).toContain('/** TypeScript package manager preference for generated package metadata. */')
+    expect(result).toContain('/** npm publishing configuration. */')
+  })
+
   it('generates record type for patternProperties-only schema without explicit type', () => {
@@ -1089,3 +1122,8 @@ const schema: JSONSchema = {
     expect(result).toBe(
-      'export type Product = {\n' +
+      '/**\n' +
+        '* Product\n' +
+        '*\n' +
+        '* A product available for purchase in the catalog.\n' +
+        '*/\n' +
+        'export type Product = {\n' +
         '  /** Unique product identifier (UUID). */\n' +
@@ -1114,3 +1152,10 @@ '  id: string;\n' +
 
-    expect(result).toBe('export type ThemeColor = "red" | "green" | "blue" | "yellow" | "purple";')
+    expect(result).toBe(
+      '/**\n' +
+        '* ThemeColor\n' +
+        '*\n' +
+        '* One of the supported theme colors.\n' +
+        '*/\n' +
+        'export type ThemeColor = "red" | "green" | "blue" | "yellow" | "purple";',
+    )
   })
@@ -1134,3 +1179,8 @@
     expect(result).toBe(
-      'export type GeoCoordinate = {\n' +
+      '/**\n' +
+        '* GeoCoordinate\n' +
+        '*\n' +
+        '* A geographic coordinate pair.\n' +
+        '*/\n' +
+        'export type GeoCoordinate = {\n' +
         '  /** Degrees latitude, from -90 to 90. */\n' +
@@ -1137,0 +1187,0 @@ '  latitude: number;\n' +

src/generate-type-definition.ts

@@ -345,2 +345,41 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
         const readonlyPrefix = options.readonly ? 'readonly ' : ''
+        const hasDescriptions = Object.values(schema.properties).some(
+          (p) => isSchemaObject(p) && (typeof p.description === 'string' || typeof p.$comment === 'string'),
+        )
+
+        if (hasDescriptions) {
+          let properties = ''
+          let first = true
+          for (const key in schema.properties) {
+            // schema.properties[key] is safe: key comes from iterating schema.properties
+            const propSchema = schema.properties[key]!
+            const isRequired = schema.required?.includes(key) ?? false
+            const optional = isRequired ? '' : '?'
+            const propType = getTypeScriptType(propSchema, options)
+            const inlineDescription =
+              isSchemaObject(propSchema) && typeof propSchema.description === 'string'
+                ? propSchema.description
+                : isSchemaObject(propSchema) && typeof propSchema.$comment === 'string'
+                  ? propSchema.$comment
+                  : undefined
+            if (!first) properties += '\n'
+            first = false
+            if (inlineDescription) {
+              properties +=
+                '  /** ' +
+                inlineDescription +
+                ' */\n  ' +
+                readonlyPrefix +
+                safeKey(key) +
+                optional +
+                ': ' +
+                propType +
+                ';'
+            } else {
+              properties += '  ' + readonlyPrefix + safeKey(key) + optional + ': ' + propType + ';'
+            }
+          }
+          return '{\n' + properties + '\n}'
+        }
+
         let properties = ''
@@ -400,4 +439,8 @@ let first = true
 
-    if (isSchemaObject(schema) && schema.$comment && typeof schema.$comment === 'string') {
-      result += buildJsDocBlock(typeName, schema.$comment)
+    const topLevelComment =
+      (isSchemaObject(schema) && typeof schema.description === 'string' && schema.description) ||
+      (isSchemaObject(schema) && typeof schema.$comment === 'string' && schema.$comment) ||
+      undefined
+    if (topLevelComment) {
+      result += buildJsDocBlock(typeName, topLevelComment)
     }
@@ -416,5 +459,9 @@
 
-    if (isSchemaObject(schema) && schema.$comment && typeof schema.$comment === 'string') {
+    const topLevelComment =
+      (isSchemaObject(schema) && typeof schema.description === 'string' && schema.description) ||
+      (isSchemaObject(schema) && typeof schema.$comment === 'string' && schema.$comment) ||
+      undefined
+    if (topLevelComment) {
       jsDocTitle = typeName
-      jsDocDescription = schema.$comment
+      jsDocDescription = topLevelComment
     }
@@ -421,0 +468,0 @@

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

236599

2.2%

Lines of code

5922

2.05%

No dependency changes