expo-type-information 0.0.2 → 0.0.4

package/src/typeInformation.ts

@@ -8,6 +8,9 @@ import {
 } from './swift/sourcekittenTypeInformation';
 import { taskAll } from './utils';
 
+/**
+ * Represents the kind of a parsed identifier from a native file.
+ */
 export enum IdentifierKind {
   BASIC,
   ENUM,
@@ -15,40 +18,85 @@ export enum IdentifierKind {
   CLASS,
 }
 
+/**
+ * Represents a parametrized type, that is a generic type with specified parameters e.g. Map<string, number>.
+ */
 export type ParametrizedType = {
   name: TypeIdentifier;
   types: Type[];
 };
 
+/**
+ * Represents an argument passed to a function or constructor.
+ */
 export type Argument = { name: string | undefined; type: Type };
+
+/**
+ * Represents a single field within a record or a struct.
+ */
 export type Field = Argument;
 
+/**
+ * Represents a struct or dictionary-like record consisting of named fields.
+ */
 export type RecordType = {
   name: string;
   fields: Field[];
 };
 
+/**
+ * Represents a single case inside an enum declaration.
+ */
 export type EnumCase = string;
 
+/**
+ * Represents an enum type, containing its name and all associated cases.
+ */
 export type EnumType = {
   name: string;
   cases: EnumCase[];
 };
 
+/**
+ * Represents a union or a sum type where a value can be one of several different types.
+ */
 export type SumType = {
   types: Type[];
 };
 
+/**
+ * Represents a dictionary type, defining the explicit types for its keys and values.
+ */
 export type DictionaryType = {
   key: Type;
   value: Type;
 };
 
+/**
+ * Represents an optional type that can also resolve to null or undefined.
+ * > **Note:** The information that this type is optional is implicit and exists only in the type system and on the parent type. There is no field on the `OptionalType` object that explicitly indicates that.
+ */
 export type OptionalType = Type;
+
+/**
+ * Represents a list or array of a specific type.
+ * > **Note:** The information that this type is array is implicit and exists only in the type system and on the parent type. There is no field on the `ArrayType` object that explicitly indicates that.
+ */
 export type ArrayType = Type;
+
+/**
+ * Represents a type identifier as a string reference.
+ */
 export type TypeIdentifier = string;
+
+/**
+ * Represents an anonymous type, a one that is not named instead written directly in the code, such as inline generics, arrays, or optionals.
+ */
 export type AnonymousType = ParametrizedType | SumType | OptionalType | DictionaryType | ArrayType;
 
+/**
+ * Categorizes the type node within the abstract syntax tree.
+ */
 export enum TypeKind {
   BASIC,
   IDENTIFIER,
@@ -59,6 +107,9 @@ export enum TypeKind {
   DICTIONARY,
 }
 
+/**
+ * Represents a basic type that is not user defined.
+ */
 export enum BasicType {
   ANY,
   STRING,
@@ -66,32 +117,55 @@ export enum BasicType {
   BOOLEAN,
   VOID,
   UNDEFINED,
+  /** Represents a type that couldn't be resolved */
   UNRESOLVED,
 }
 
+/**
+ * Represents an abstract type node.
+ */
 export type Type = {
   kind: TypeKind;
   type: BasicType | TypeIdentifier | AnonymousType;
 };
 
+/**
+ * Represents a DSL property declaration.
+ */
 export type PropertyDeclaration = ConstantDeclaration;
+
+/**
+ * Represents a DSL view declaration.
+ */
 export type ViewDeclaration = ModuleClassDeclaration;
+
+/**
+ * Represents a DSL event declaration.
+ */
 export type EventDeclaration = string;
 
 /**
- * Retain information of where the thing was defined in the file.
+ * Retains information of where the thing was defined in the file.
  * As collecting type information is written in asynchronous way it is non-deterministic.
- * To make it deterministic we just sort the declaration by the definitionOffset, maintianing the same ordering as in original file.
+ * To make it deterministic we just sort the declaration by the definitionOffset, maintaining the same ordering as in original file.
+ * @header TypeInfoTypes
  */
 export type DefinitionOffset = {
   definitionOffset: number;
 };
 
+/**
+ * Represents a DSL constant declaration.
+ */
 export type ConstantDeclaration = {
   name: string;
   type: Type;
 } & DefinitionOffset;
 
+/**
+ * Represents a DSL function declaration.
+ * @hideType
+ */
 export type FunctionDeclaration = {
   name: string;
   returnType: Type;
@@ -99,15 +173,24 @@ export type FunctionDeclaration = {
   parameters: Type[];
 } & DefinitionOffset;
 
+/**
+ * Represents a DSL prop declaration.
+ */
 export type PropDeclaration = {
   name: string;
   arguments: Argument[];
 } & DefinitionOffset;
 
+/**
+ * Represents a DSL class constructor declaration.
+ */
 export type ConstructorDeclaration = {
   arguments: Argument[];
 } & DefinitionOffset;
 
+/**
+ * Represents a DSL native class declaration.
+ */
 export type ClassDeclaration = {
   name: string;
   constructor: ConstructorDeclaration | null;
@@ -116,6 +199,9 @@ export type ClassDeclaration = {
   properties: PropertyDeclaration[];
 } & DefinitionOffset;
 
+/**
+ * Represents a DSL module declaration.
+ */
 export type ModuleClassDeclaration = {
   name: string;
   constructor: ConstructorDeclaration | null;
@@ -129,15 +215,27 @@ export type ModuleClassDeclaration = {
   events: EventDeclaration[];
 } & DefinitionOffset;
 
+/**
+ * Represents a definition of an identifier.
+ */
 export type IdentifierDefinition = {
   kind: IdentifierKind;
   definition: string | RecordType | EnumType | ClassDeclaration;
 };
 
+/**
+ * Maps type identifier strings to their definition objects.
+ */
 export type TypeIdentifierDefinitionMap = Map<string, IdentifierDefinition>;
 
+/**
+ * Serialized version of the `TypeIdentifierDefinitionMap`.
+ */
 export type TypeIdentifierDefinitionList = [string, IdentifierDefinition][];
 
+/**
+ * Serialized version of the `FileTypeInformation`, suitable for JSON storage or testing environments.
+ */
 export type FileTypeInformationSerialized = {
   usedTypeIdentifiersList: string[];
   declaredTypeIdentifiersList: string[];
@@ -149,9 +247,10 @@ export type FileTypeInformationSerialized = {
 };
 
 /**
- * FileTypeInformation object abstracts over type related information in a file.
+ * `FileTypeInformation` object abstracts over type related information in a file.
  * The abstraction is closely related to Typescript and expo NativeModules (both to be independent of the actual native side
  * and to give accurate information about what and how we can use the given module).
+ * @header TypeInfoTypes
  */
 export type FileTypeInformation = {
   /**
@@ -190,9 +289,10 @@ export type FileTypeInformation = {
 };
 
 /**
- * Used for testing purposes, maps Sets and Maps to Arrays and returns FileTypeInformationSerialized object which can be written to a JSON.
- * @param param0 FileTypeInformation object to serialize.
- * @returns FileTypeInformationSerialized object.
+ * Used for testing purposes, maps Sets and Maps to Arrays and returns `FileTypeInformationSerialized` object which can be written to a JSON.
+ * @param fileTypeinformation `FileTypeInformation` object to serialize.
+ * @returns a `FileTypeInformationSerialized` object.
+ * @header TypeInformationAbstraction
  */
 export function serializeTypeInformation({
   usedTypeIdentifiers,
@@ -215,9 +315,10 @@ export function serializeTypeInformation({
 }
 
 /**
- * Used for testing purposes, maps Arrays to Sets and Maps depending on the field and returns FileTypeInformation object.
- * @param param0 FileTypeInformationSerialized object to deserialize.
- * @returns FileTypeInformation object.
+ *  Used for testing purposes, maps Arrays to Sets and Maps depending on the field and returns `FileTypeInformation` object.
+ * @param fileTypeinformationSerialized `FileTypeInformationSerialized` object to deserialize.
+ * @returns `FileTypeInformation` object.
+ * @header TypeInformationAbstraction
  */
 export function deserializeTypeInformation({
   usedTypeIdentifiersList,
@@ -241,7 +342,7 @@ export function deserializeTypeInformation({
 
 /**
  * Defines the level of type inference to apply when extracting type information.
- * Note: In case where type inference is on, it may take more then twice the time to compute the type information.
+ * > **Note:** In case where type inference is on, it may take more then twice the time to compute the type information.
  */
 export enum TypeInferenceOption {
   /** No type inference will be performed. */
@@ -252,12 +353,18 @@ export enum TypeInferenceOption {
   PREPROCESS_AND_INFERENCE,
 }
 
+/**
+ * Defines an input option for extracting type information directly from a raw string of source code.
+ */
 export type StringInputOption = {
   type: 'string';
   fileContent: string;
   language: 'Swift';
 };
 
+/**
+ * Defines an input option for extracting type information from a set of physical files.
+ */
 export type FileInputOption = {
   type: 'file';
   inputFileAbsolutePaths: string[];
@@ -292,12 +399,33 @@ async function withTempFile<T>(content: string, fn: (filePath: string) => Promis
   }
 }
 
+export async function withPreparedSingleFile<T>(
+  { input, typeInference }: GetFileTypeInformationOptions,
+  fn: (filePath: string) => Promise<T>
+): Promise<T> {
+  const shouldPreprocessFile = typeInference === TypeInferenceOption.PREPROCESS_AND_INFERENCE;
+  if (!shouldPreprocessFile && input.type === 'file' && input.inputFileAbsolutePaths.length === 0) {
+    return fn(input.inputFileAbsolutePaths[0] as string);
+  }
+
+  const fileContent =
+    input.type === 'file'
+      ? await mergeFileContents(input.inputFileAbsolutePaths)
+      : input.fileContent;
+
+  if (shouldPreprocessFile) {
+    return withTempFile(preprocessSwiftFile(fileContent), fn);
+  }
+  return withTempFile(fileContent, fn);
+}
+
 /**
  * Reads and extracts `FileTypeInformation` from either a provided file path or a raw string of source code.
  * If a raw string is provided, or if the `PREPROCESS_AND_INFERENCE` inference option is selected,
  * the function will create a temporary file with the (optionally preprocessed) content to facilitate parsing.
  * @param options - Configuration object containing the input source (file or string) and the desired level of type inference.
- * @returns A promise that resolves to a `FileTypeInformation` object if the input was parsed successfully. Otherwise, it returns `null`.
+ * @returns A promise that resolves to a `FileTypeInformation` object if the input was parsed successfully. Otherwise, it resolves to `null`.
+ * @header TypeInformationAbstraction
  */
 export async function getFileTypeInformation({
   input,
@@ -311,16 +439,7 @@ export async function getFileTypeInformation({
     });
   }
 
-  const fileContent =
-    input.type === 'file'
-      ? await mergeFileContents(input.inputFileAbsolutePaths)
-      : input.fileContent;
-
-  const preprocessedContent = shouldPreprocessFile ? preprocessSwiftFile(fileContent) : fileContent;
-
-  return withTempFile(preprocessedContent, async (tempFilePath) => {
-    return getSwiftFileTypeInformation(tempFilePath, {
-      typeInference: typeInferenceOn,
-    });
+  return withPreparedSingleFile({ input, typeInference }, async (tempFilePath) => {
+    return getSwiftFileTypeInformation(tempFilePath, { typeInference: typeInferenceOn });
   });
 }

package/src/typescriptGeneration.ts

@@ -40,8 +40,17 @@ const voidKeywordType = () => ts.factory.createKeywordTypeNode(ts.SyntaxKind.Voi
 
 const newlineIdentifier = () => ts.factory.createIdentifier('\n\n');
 
+/**
+ * A helper type which contains the generated file content and name.
+ */
 export type OutputFile = {
+  /**
+   * @field Generated file content.
+   */
   content: string;
+  /**
+   * @field Generated file base name (e.g. `ExpoSettings.types.ts`).
+   */
   name: string;
 };
 
@@ -717,7 +726,9 @@ export function buildEnumTypeDeclaration(
   return ts.factory.createEnumDeclaration(
     constructModifiersArray({ exported, declare: declared }),
     enumType.name,
-    enumType.cases.map((enumcase) => ts.factory.createEnumMember(enumcase))
+    enumType.cases.map((enumcase) =>
+      ts.factory.createEnumMember(enumcase, ts.factory.createStringLiteral(enumcase))
+    )
   );
 }
 
@@ -999,6 +1010,14 @@ async function tsNodesToString(elements: ts.Node[]): Promise<string> {
   return await prettifyCode(printedTs, 'typescript');
 }
 
+/**
+ * Helper function that takes a file content string and formats it using `prettier` formatter.
+ * @param text Content of a JavaScript/TypeScript file to format.
+ * @param parser An option of which parser to use to format the file.
+ * @default "babel"
+ * @returns A promise which resolves to the `text` string after formatting using `prettier` with the given `parser`.
+ * @header TypescriptGeneration
+ */
 export async function prettifyCode(text: string, parser: 'babel' | 'typescript' = 'babel') {
   return await prettier.format(text, {
     parser,
@@ -1009,6 +1028,12 @@ export async function prettifyCode(text: string, parser: 'babel' | 'typescript'
   });
 }
 
+/**
+ * Generates the TypeScript string content for a native View's type declaration file.
+ * @param fileTypeInformation The abstracted type information of an Expo module.
+ * @returns A promise that resolves to a string containing the TypeScript declaration file content or `null` if the generation has failed.
+ * @header TypescriptGeneration
+ */
 export async function generateViewTypesFileContent(
   fileTypeInformation: FileTypeInformation
 ): Promise<string | null> {
@@ -1019,6 +1044,12 @@ export async function generateViewTypesFileContent(
   return tsNodesToString(buildViewDeclarationNodes(ctx));
 }
 
+/**
+ * Generates the TypeScript string content for a native View's type declaration file which mounts the View props on the global `JSXIntrinsics`.
+ * @param fileTypeInformation The abstracted type information of an Expo module.
+ * @returns A promise that resolves to a string containing the TypeScript declaration file content or `null` if the generation has failed.
+ * @header TypescriptGeneration
+ */
 export async function generateJSXIntrinsicsFileContent(
   fileTypeInformation: FileTypeInformation
 ): Promise<string | null> {
@@ -1029,6 +1060,12 @@ export async function generateJSXIntrinsicsFileContent(
   return tsNodesToString(buildJSXIntrinsicsViewNodes(ctx));
 }
 
+/**
+ * Generates the TypeScript string content for a native module type declaration file.
+ * @param fileTypeInformation The abstracted type information of an Expo module.
+ * @returns A promise that resolves to a string containing the TypeScript module declaration file content or `null` if the generation has failed.
+ * @header TypescriptGeneration
+ */
 export async function generateModuleTypesFileContent(
   fileTypeInformation: FileTypeInformation
 ): Promise<string | null> {
@@ -1039,6 +1076,13 @@ export async function generateModuleTypesFileContent(
   return tsNodesToString(buildModuleDeclarationNodes(ctx));
 }
 
+/**
+ * Generates a short TypeScript interface for an Expo module. This creates the content for two files: a volatile generated file containing raw type definitions,
+ * and a stable user-facing file that wraps and exports the native module methods in new functions.
+ * @param fileTypeInformation The abstracted type information of an Expo module.
+ * @returns A promise that resolves to an object containing the string contents for both the volatile generated file and the stable TypeScript interface file.
+ * @header TypescriptGeneration
+ */
 export async function generateConciseTsInterface(
   fileTypeInformation: FileTypeInformation
 ): Promise<{
@@ -1062,6 +1106,14 @@ export async function generateConciseTsInterface(
   };
 }
 
+/**
+ * Generates a full, multi-file TypeScript interface for an Expo module.
+ * The generated interface is separated into a file with type definitions, a file which wraps the native module, a file for each view defined in a module and an index file which reexports all definitions from the other files.
+ *
+ * @param fileTypeInformation The abstracted type information of an Expo module.
+ * @returns A promise that resolves to an object containing the string contents for all of the generated files or `null` if the generation has failed.
+ * @header TypescriptGeneration
+ */
 export async function generateFullTsInterface(fileTypeInformation: FileTypeInformation): Promise<{
   moduleTypesFile: OutputFile;
   moduleViewsFiles: OutputFile[];

package/tests/__snapshots__/typeInformation.test.ts.snap

@@ -34,11 +34,11 @@ export type TestRecordClass = {
 };
 
 export enum TestEnum {
-  simpleCase,
-  multipleCases1,
-  multipleCases2,
-  caseWithArgs1,
-  caseWithArgs2
+  simpleCase = 'simpleCase',
+  multipleCases1 = 'multipleCases1',
+  multipleCases2 = 'multipleCases2',
+  caseWithArgs1 = 'caseWithArgs1',
+  caseWithArgs2 = 'caseWithArgs2'
 }
 
 export declare class TestClassWithConstructor {
@@ -298,11 +298,11 @@ export type TestRecordClass = {
 };
 
 export enum TestEnum {
-  simpleCase,
-  multipleCases1,
-  multipleCases2,
-  caseWithArgs1,
-  caseWithArgs2
+  simpleCase = 'simpleCase',
+  multipleCases1 = 'multipleCases1',
+  multipleCases2 = 'multipleCases2',
+  caseWithArgs1 = 'caseWithArgs1',
+  caseWithArgs2 = 'caseWithArgs2'
 }
 
 export declare class TestClassWithConstructor {
@@ -387,11 +387,11 @@ export type TestRecordClass = {
 
 
 export enum TestEnum {
-    simpleCase,
-    multipleCases1,
-    multipleCases2,
-    caseWithArgs1,
-    caseWithArgs2
+    simpleCase = "simpleCase",
+    multipleCases1 = "multipleCases1",
+    multipleCases2 = "multipleCases2",
+    caseWithArgs1 = "caseWithArgs1",
+    caseWithArgs2 = "caseWithArgs2"
 }
 
 
@@ -454,11 +454,11 @@ exports[`Same generated mock file JS 1`] = `
  *  */
 export var TestEnum;
 (function (TestEnum) {
-    TestEnum[TestEnum["simpleCase"] = 0] = "simpleCase";
-    TestEnum[TestEnum["multipleCases1"] = 1] = "multipleCases1";
-    TestEnum[TestEnum["multipleCases2"] = 2] = "multipleCases2";
-    TestEnum[TestEnum["caseWithArgs1"] = 3] = "caseWithArgs1";
-    TestEnum[TestEnum["caseWithArgs2"] = 4] = "caseWithArgs2";
+    TestEnum["simpleCase"] = "simpleCase";
+    TestEnum["multipleCases1"] = "multipleCases1";
+    TestEnum["multipleCases2"] = "multipleCases2";
+    TestEnum["caseWithArgs1"] = "caseWithArgs1";
+    TestEnum["caseWithArgs2"] = "caseWithArgs2";
 })(TestEnum || (TestEnum = {}));
 export function SimpleFunction(a, b) { return 0; }
 export function TestUntypedFunction() { return ""; }
@@ -517,11 +517,11 @@ export type TestRecordClass = {
 };
 
 export enum TestEnum {
-  simpleCase,
-  multipleCases1,
-  multipleCases2,
-  caseWithArgs1,
-  caseWithArgs2
+  simpleCase = 'simpleCase',
+  multipleCases1 = 'multipleCases1',
+  multipleCases2 = 'multipleCases2',
+  caseWithArgs1 = 'caseWithArgs1',
+  caseWithArgs2 = 'caseWithArgs2'
 }
 
 export declare class TestClassWithConstructor {