flow-api-translator 0.330.0 → 0.332.0

package/dist/src/flowToFlowDef.js

@@ -10,6 +10,120 @@ var _TranslationUtils = require("./utils/TranslationUtils");
 var _ErrorUtils = require("./utils/ErrorUtils");
 var _flowEstree = require("flow-estree");
 const EMPTY_TRANSLATION_RESULT = [null, []];
+function isDocComment(comment) {
+  return comment.type === 'Block' && comment.value.startsWith('*') && !/@(flow|noflow|format)\b/.test(comment.value) && !comment.value.includes('Copyright');
+}
+function findDefaultExport(body) {
+  for (const statement of body) {
+    if (statement.type === 'ExportDefaultDeclaration' || statement.type === 'DeclareExportDeclaration' && statement.default === true) {
+      return statement;
+    }
+  }
+  return null;
+}
+function getExportedIdentifierName(defaultExport) {
+  const declaration = defaultExport.declaration;
+  if (declaration == null) {
+    return null;
+  }
+  let node = declaration;
+  while (node.type === 'AsExpression' || node.type === 'TypeCastExpression') {
+    node = node.expression;
+  }
+  if (node.type === 'TypeofTypeAnnotation') {
+    return node.argument.type === 'Identifier' ? node.argument.name : null;
+  }
+  return node.type === 'Identifier' ? node.name : null;
+}
+function findDeclarationByName(body, name) {
+  for (const statement of body) {
+    const declaration = statement.type === 'ExportNamedDeclaration' && statement.declaration != null ? statement.declaration : statement;
+    if ((declaration.type === 'ClassDeclaration' || declaration.type === 'FunctionDeclaration' || declaration.type === 'ComponentDeclaration') && declaration.id != null && declaration.id.name === name) {
+      return {
+        kind: declaration.type,
+        statement
+      };
+    }
+    if (declaration.type === 'VariableDeclaration' || declaration.type === 'DeclareVariable') {
+      for (const declarator of declaration.declarations) {
+        if (declarator.id.type === 'Identifier' && declarator.id.name === name) {
+          return {
+            kind: declaration.type,
+            statement
+          };
+        }
+      }
+    }
+  }
+  return null;
+}
+function findDisplayName(body, name) {
+  for (const statement of body) {
+    if (statement.type === 'ExpressionStatement' && statement.expression.type === 'AssignmentExpression') {
+      const {
+        left,
+        right
+      } = statement.expression;
+      if (left.type === 'MemberExpression' && left.object.type === 'Identifier' && left.object.name === name && left.property.type === 'Identifier' && left.property.name === 'displayName' && right.type === 'Literal' && typeof right.value === 'string') {
+        return right.value;
+      }
+    }
+  }
+  return null;
+}
+function applyDefaultExportDocPlacement(body, translatedStatements, placement, code) {
+  if (placement === 'declaration') {
+    return code;
+  }
+  const defaultExport = findDefaultExport(body);
+  if (defaultExport == null || (0, _flowTransform.getLeadingCommentsForNode)(defaultExport).some(isDocComment)) {
+    return code;
+  }
+  const exportedName = getExportedIdentifierName(defaultExport);
+  if (exportedName == null) {
+    return code;
+  }
+  const exportedDeclaration = findDeclarationByName(body, exportedName);
+  if ((exportedDeclaration == null ? void 0 : exportedDeclaration.kind) === 'ClassDeclaration') {
+    return code;
+  }
+  const sources = [];
+  if (exportedDeclaration != null) {
+    sources.push(exportedDeclaration);
+  }
+  const displayName = findDisplayName(body, exportedName);
+  if (displayName != null && displayName !== exportedName) {
+    const displayNameDeclaration = findDeclarationByName(body, displayName);
+    if (displayNameDeclaration != null) {
+      sources.push(displayNameDeclaration);
+    }
+  }
+  const translatedDefaultExport = translatedStatements.get(defaultExport);
+  if (translatedDefaultExport == null) {
+    return code;
+  }
+  for (const source of sources) {
+    const docComments = (0, _flowTransform.getLeadingCommentsForNode)(source.statement).filter(isDocComment);
+    if (docComments.length === 0) {
+      continue;
+    }
+    let mutatedCode = code;
+    const clonedComments = docComments.map(comment => {
+      const clonedComment = (0, _flowTransform.cloneCommentWithMarkers)(comment);
+      mutatedCode = (0, _flowTransform.makeCommentOwnLine)(mutatedCode, clonedComment);
+      return clonedComment;
+    });
+    (0, _flowTransform.setCommentsOnNode)(translatedDefaultExport, [...(0, _flowTransform.getCommentsForNode)(translatedDefaultExport), ...clonedComments]);
+    if (placement === 'export') {
+      const translatedSource = translatedStatements.get(source.statement);
+      if (translatedSource != null) {
+        (0, _flowTransform.setCommentsOnNode)(translatedSource, (0, _flowTransform.getCommentsForNode)(translatedSource).filter(comment => !docComments.includes(comment)));
+      }
+    }
+    return mutatedCode;
+  }
+  return code;
+}
 function convertArray(items, convert) {
   const resultItems = [];
   const deps = [];
@@ -39,7 +153,7 @@ function transferProgramStatementProperties(stmt, orgStmt) {
   stmt.loc = orgStmt.loc;
 }
 function flowToFlowDef(ast, code, scopeManager, opts) {
-  var _ast$interpreter$valu, _ast$interpreter;
+  var _opts$defaultExportDo, _ast$interpreter$valu, _ast$interpreter;
   const context = (0, _TranslationUtils.createTranslationContext)(code, scopeManager, opts);
   const translatedStatements = new Map();
   function storeTranslatedStatement(stmt, orgStmt) {
@@ -100,9 +214,11 @@ function flowToFlowDef(ast, code, scopeManager, opts) {
     if (translatedStatement != null) {
       const optimizedStatement = stripUnusedDefs(translatedStatement, seenDeps, context);
       transferProgramStatementProperties(optimizedStatement, stmt);
+      storeTranslatedStatement(optimizedStatement, stmt);
       translatedBody.push(optimizedStatement);
     }
   }
+  const outputCode = applyDefaultExportDocPlacement(ast.body, translatedStatements, (_opts$defaultExportDo = opts.defaultExportDocPlacement) != null ? _opts$defaultExportDo : 'declaration', code);
   return [_flowTransform.t.Program({
     body: translatedBody,
     sourceType: ast.sourceType,
@@ -110,7 +226,7 @@ function flowToFlowDef(ast, code, scopeManager, opts) {
     comments: ast.comments,
     tokens: ast.tokens,
     docblock: ast.docblock
-  }), code];
+  }), outputCode];
 }
 function convertExport(stmt, context) {
   switch (stmt.type) {
@@ -740,6 +856,9 @@ function convertSuperClass(superClass, superTypeArguments, context) {
       {
         const typeAnnotation = superClass.type === 'TypeCastExpression' ? superClass.typeAnnotation.typeAnnotation : superClass.typeAnnotation;
         if (typeAnnotation.type === 'GenericTypeAnnotation') {
+          if (typeAnnotation.id.type === 'ImportType') {
+            throw (0, _ErrorUtils.translationError)(superClass, 'SuperClass: Import type not supported', context);
+          }
           return convertSuperClassHelper((0, _flowTransform.asDetachedNode)(typeAnnotation.id), typeAnnotation, superTypeArguments, context);
         }
         if (typeAnnotation.type === 'TypeofTypeAnnotation') {

package/dist/src/index.js

@@ -24,21 +24,22 @@ async function translateFlowToFlowDef(code, prettierOptions = {}, opts) {
     scopeManager
   } = await (0, _flowTransform.parse)(code);
   const [flowDefAst, mutatedCode] = (0, _flowToFlowDef.default)(ast, code, scopeManager, {
-    recoverFromErrors: true,
-    mungeUnderscores: opts == null ? void 0 : opts.mungeUnderscores
+    ...opts,
+    recoverFromErrors: true
   });
   return (0, _flowTransform.print)(flowDefAst, mutatedCode, prettierOptions);
 }
-async function translateFlowToTSDef(code, prettierOptions = {}) {
-  const flowDefCode = await translateFlowToFlowDef(code, prettierOptions);
-  return translateFlowDefToTSDef(flowDefCode, prettierOptions);
+async function translateFlowToTSDef(code, prettierOptions = {}, opts) {
+  const flowDefCode = await translateFlowToFlowDef(code, prettierOptions, opts);
+  return translateFlowDefToTSDef(flowDefCode, prettierOptions, opts);
 }
-async function translateFlowDefToTSDef(code, prettierOptions = {}) {
+async function translateFlowDefToTSDef(code, prettierOptions = {}, opts) {
   const {
     ast,
     scopeManager
   } = await (0, _flowTransform.parse)(code);
   const [tsAST, mutatedCode] = (0, _flowDefToTSDef.flowDefToTSDef)(code, ast, scopeManager, {
+    ...opts,
     recoverFromErrors: true
   });
   return (0, _flowTransform.print)(tsAST, mutatedCode, {

package/dist/src/utils/TSNodeUtils.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.ensureTypeIncludesUndefined = ensureTypeIncludesUndefined;
 exports.extractPropertyKeyLiterals = extractPropertyKeyLiterals;
+exports.getDefaultExportBindingName = getDefaultExportBindingName;
 var TSESTree = _interopRequireWildcard(require("./ts-estree-ast-types"));
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const DUMMY_LOC = {
@@ -17,6 +18,25 @@ const DUMMY_LOC = {
     column: 0
   }
 };
+function inferDefaultExportName(typeAnnotation) {
+  switch (typeAnnotation.type) {
+    case 'GenericTypeAnnotation':
+      return typeAnnotation.id.type === 'Identifier' && typeAnnotation.id.name !== '$FlowFixMe' ? typeAnnotation.id.name : null;
+    case 'NullableTypeAnnotation':
+      return inferDefaultExportName(typeAnnotation.typeAnnotation);
+    case 'TypeofTypeAnnotation':
+      return typeAnnotation.argument.type === 'Identifier' && typeAnnotation.argument.name !== '$FlowFixMe' ? typeAnnotation.argument.name : null;
+    default:
+      return null;
+  }
+}
+function getDefaultExportBindingName(typeAnnotation, useSemanticName) {
+  if (!useSemanticName) {
+    return '$$EXPORT_DEFAULT_DECLARATION$$';
+  }
+  const inferredName = inferDefaultExportName(typeAnnotation);
+  return inferredName == null ? '$$default' : `$$${inferredName}`;
+}
 function extractPropertyKeyLiterals(members) {
   if (members.length === 0) {
     return null;

package/dist/utils/TSNodeUtils.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.ensureTypeIncludesUndefined = ensureTypeIncludesUndefined;
 exports.extractPropertyKeyLiterals = extractPropertyKeyLiterals;
+exports.getDefaultExportBindingName = getDefaultExportBindingName;
 var TSESTree = _interopRequireWildcard(require("./ts-estree-ast-types"));
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const DUMMY_LOC = {
@@ -17,6 +18,25 @@ const DUMMY_LOC = {
     column: 0
   }
 };
+function inferDefaultExportName(typeAnnotation) {
+  switch (typeAnnotation.type) {
+    case 'GenericTypeAnnotation':
+      return typeAnnotation.id.type === 'Identifier' && typeAnnotation.id.name !== '$FlowFixMe' ? typeAnnotation.id.name : null;
+    case 'NullableTypeAnnotation':
+      return inferDefaultExportName(typeAnnotation.typeAnnotation);
+    case 'TypeofTypeAnnotation':
+      return typeAnnotation.argument.type === 'Identifier' && typeAnnotation.argument.name !== '$FlowFixMe' ? typeAnnotation.argument.name : null;
+    default:
+      return null;
+  }
+}
+function getDefaultExportBindingName(typeAnnotation, useSemanticName) {
+  if (!useSemanticName) {
+    return '$$EXPORT_DEFAULT_DECLARATION$$';
+  }
+  const inferredName = inferDefaultExportName(typeAnnotation);
+  return inferredName == null ? '$$default' : `$$${inferredName}`;
+}
 function extractPropertyKeyLiterals(members) {
   if (members.length === 0) {
     return null;

package/dist/utils/TSNodeUtils.js.flow

@@ -10,7 +10,7 @@
 
 'use strict';
 
-import type {SourceLocation} from 'flow-estree';
+import type {SourceLocation, TypeAnnotationType} from 'flow-estree';
 
 import * as TSESTree from './ts-estree-ast-types';
 
@@ -19,6 +19,51 @@ const DUMMY_LOC: SourceLocation = {
   end: {line: 1, column: 0},
 };
 
+/**
+ * Returns the identifier referenced by a default-exported Flow type, unwrapping
+ * nullable types, or `null` when the type does not reference exactly one
+ * identifier.
+ *
+ * `$FlowFixMe` is rejected because it translates to `any`, so naming the
+ * binding after it would describe the recovery placeholder rather than the
+ * exported type.
+ */
+function inferDefaultExportName(
+  typeAnnotation: TypeAnnotationType,
+): string | null {
+  switch (typeAnnotation.type) {
+    case 'GenericTypeAnnotation':
+      return typeAnnotation.id.type === 'Identifier' &&
+        typeAnnotation.id.name !== '$FlowFixMe'
+        ? typeAnnotation.id.name
+        : null;
+    case 'NullableTypeAnnotation':
+      return inferDefaultExportName(typeAnnotation.typeAnnotation);
+    case 'TypeofTypeAnnotation':
+      return typeAnnotation.argument.type === 'Identifier' &&
+        typeAnnotation.argument.name !== '$FlowFixMe'
+        ? typeAnnotation.argument.name
+        : null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Returns the binding name to use when TypeScript requires a synthetic value
+ * for a Flow default export.
+ */
+export function getDefaultExportBindingName(
+  typeAnnotation: TypeAnnotationType,
+  useSemanticName: boolean,
+): string {
+  if (!useSemanticName) {
+    return '$$EXPORT_DEFAULT_DECLARATION$$';
+  }
+  const inferredName = inferDefaultExportName(typeAnnotation);
+  return inferredName == null ? '$$default' : `$$${inferredName}`;
+}
+
 /**
  * Extract statically known property key names from a list of TS type element
  * nodes and return them as `TSLiteralType` (string literal) AST nodes.

package/dist/utils/TranslationUtils.js.flow

@@ -14,9 +14,25 @@ import type {Identifier, JSXIdentifier} from 'flow-estree';
 import type {ScopeManager, Variable} from 'flow-eslint';
 
 export type Dep = string;
+
+/**
+ * Where the documentation for a default-exported value should end up.
+ *
+ * TypeScript resolves a default re-export to the synthetic `export default`
+ * symbol rather than the declaration it aliases, so consumers that care about
+ * doc comments surviving a re-export need `'export'` or `'both'`.
+ */
+export type DefaultExportDocPlacement = 'both' | 'declaration' | 'export';
+
 export type TranslationOptions = {
+  defaultExportDocPlacement?: DefaultExportDocPlacement,
   recoverFromErrors: boolean,
   mungeUnderscores?: boolean,
+  /**
+   * Name synthetic default exports after their referenced identifier, falling
+   * back to `$$default` for anonymous types. Defaults to false.
+   */
+  useSemanticDefaultExportNames?: boolean,
 };
 export type TranslationContext = {
   scopeManager: ScopeManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-api-translator",
-  "version": "0.330.0",
+  "version": "0.332.0",
   "description": "Toolkit for creating Flow and TypeScript compatible libraries from Flow source code.",
   "homepage": "https://flow.org",
   "license": "MIT",
@@ -14,10 +14,10 @@
     "@typescript-eslint/parser": "8.38.0",
     "@typescript-eslint/visitor-keys": "8.38.0",
     "flow-enums-runtime": "^0.0.6",
-    "flow-eslint": "0.330.0",
-    "flow-estree": "0.330.0",
-    "flow-parser": "0.330.0",
-    "flow-transform": "0.330.0",
+    "flow-eslint": "0.332.0",
+    "flow-estree": "0.332.0",
+    "flow-parser": "0.332.0",
+    "flow-transform": "0.332.0",
     "typescript": "5.3.2"
   },
   "peerDependencies": {