expo-type-information 0.0.2 → 0.0.3

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[];
@@ -297,7 +404,8 @@ async function withTempFile<T>(content: string, fn: (filePath: string) => Promis
  * 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,

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;
 };
 
@@ -999,6 +1008,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 +1026,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 +1042,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 +1058,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 +1074,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 +1104,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[];