Expo 类型生成参考

关于Expo类型信息包的参考资料。

警告 expo-type-information 库仅适用于 macOS。适用于 SDK 56 及更高版本。

expo-type-information 包提供用于自动为 Swift 模块生成 TypeScript 接口的工具。它由多个部分组成：

🌐 The expo-type-information package provides tools to automatically generate TypeScript interface for Swift modules. It consists of multiple parts:

基于 sourcekitten 的 Swift 解析器：一个可以从 Swift Expo 模块中检索并结构化类型信息的解析器。
类型抽象：对与 Expo 模块相关的类型信息进行抽象，解析器以这种抽象的方式返回信息。
TypeScript AST 触发器：一组帮助生成 TypeScript 代码的函数。
CLI：一个命令行工具，集成了上述功能。

配置

🌐 Configuration

安装 expo-type-information 库：

🌐 Install the expo-type-information library:

Terminal

- npx expo install expo-type-information

- yarn expo install expo-type-information

- pnpm expo install expo-type-information

- bun expo install expo-type-information

要使用这个软件包，你还需要安装 sourcekitten。你可以使用 macOS 的包管理器，比如 Homebrew。

🌐 To use this package you also need to have sourcekitten installed. You can use macOS package manager like Homebrew.

Terminal

- brew install sourcekitten

命令行接口参考

🌐 CLI reference

常用 CLI 选项

🌐 Common CLI options

本库中的每个 CLI 命令都使用以下通用选项进行配置。唯一的例外是 inline-modules-interface，它的选项略有不同。

🌐 Every CLI command in this library uses the following common options for configuration. The only exception is the inline-modules-interface which has slightly different options.

标志	描述	默认
`-i, --input-paths <filePaths...>`	某个模块的 Swift 文件路径，允许使用通配符模式。
`-m --module-path <modulePath>`	Expo 模块根目录的路径。
`-o, --output-path <filePath>`	保存生成输出的路径。如果未提供此选项，生成的输出将打印到控制台。
`-t, --type-inference <typeInference>`	类型推断的级别：`NO_INFERENCE`、`SIMPLE_INFERENCE` 或 `PREPROCESS_AND_INFERENCE`。请注意，`PREPROCESS_AND_INFERENCE` 选项在某些模块上偶尔会失败。如果遇到错误，请回退到 `SIMPLE_INFERENCE` 或 `NO_INFERENCE`。	`PREPROCESS_AND_INFERENCE`
`-s, --skip-unicode-character-mapping`	跳过将文件中的所有非 ASCII 字符映射为 ASCII 字符串。默认情况下会执行此映射，因为 SourceKitten 在计算非 ASCII 字符的偏移量时不一致。
`-w --watcher`	启动一个监视器，用于检查输入路径文件的更改。

主要命令

🌐 Main commands

`module-interface`

为 Swift 模块生成完整的 TypeScript 接口。它包括：

🌐 Generates a full TypeScript interface for a Swift module. It consists of:

types.ts 文件，定义了模块中的所有类型
module.ts 与本地模块定义
view.tsx 用于模块中定义的每个视图
index.ts 文件重新导出一些函数

接受标准的常用 CLI 选项。

`inline-modules-interface`

为项目中的每个 Swift 内联模块创建一个 TypeScript 接口。该接口由两个文件组成：

🌐 Creates a TypeScript interface for every Swift inline module in the project. The interface consists of two files:

Module.generated.ts：每次运行该命令时都会重新生成
Module.tsx：如果你更改它，它不会被重新生成

选项：

标志	描述	默认
`-a --app-json <appJsonPath>`	到定义 `inline.modules.watchedDirectories` 的应用配置文件的路径。
`-w --watcher`	启动一个检查内联模块文件更改的监视器。
`-t, --type-inference <typeInference>`	类型推断的等级：`NO_INFERENCE`、`SIMPLE_INFERENCE` 或 `PREPROCESS_AND_INFERENCE`。请注意，`PREPROCESS_AND_INFERENCE` 选项在某些模块上有时会失败。如果遇到错误，请回退到 `SIMPLE_INFERENCE` 或 `NO_INFERENCE`。	`SIMPLE_INFERENCE`

`short-module-interface`

为 Expo 模块创建一个简短的 TypeScript 接口。会覆盖 ModuleName.generated.ts 并在不存在时创建 ModuleName.ts。可与内联模块一起使用。

🌐 Creates a short TypeScript interface for an Expo module. Overwrites ModuleName.generated.ts and creates ModuleName.ts if not present. Can be used with inline-modules.

接受标准的常用 CLI 选项。

`generate-mocks-for-file`

为给定的 expo 模块生成模拟数据。

🌐 Generates mocks for a given expo module.

接受标准的常用 CLI 选项。

其他命令

🌐 Other commands

这些命令是内部的或非常特定的。

🌐 These commands are internal or very specific.

本节中的所有命令都接受标准的常用 CLI 选项。

`other type-information`

解析 Swift 模块类型信息并输出 FileTypeInformation JSON。

🌐 Parses Swift module type information and outputs a FileTypeInformation JSON.

`other generate-module-types`

为模块生成类型声明文件内容。

🌐 Generates a type declaration file content for a module.

`other generate-view-types`

为本地视图生成类型声明文件。

🌐 Generates a type declaration file for a native View.

`other generate-jsx-intrinsics`

为视图生成声明文件，使用视图属性更新 JSX 内置元素。

🌐 Generates a declaration file for a View, updates JSX intrinsics with the View props.

`other preprocess-file`

打印在使用 sourcekitten 解析之前的预处理文件状态。它有助于检查 --module-path、--input-path 和 --type-inference 选项如何影响解析后的文件。

🌐 Print the preprocessed file(s) in the state right before parsing them using sourcekitten. It helps with checking how the --module-path, --input-path, and --type-inference options affect the parsed file.

Type information abstraction

`deserializeTypeInformation(fileTypeinformationSerialized)`

Parameter	Type	Description
fileTypeinformationSerialized	`FileTypeInformationSerialized`	`FileTypeInformationSerialized` object to deserialize.

Used for testing purposes, maps Arrays to Sets and Maps depending on the field and returns FileTypeInformation object.

Returns:

FileTypeInformation

FileTypeInformation object.

`getFileTypeInformation(options)`

Parameter	Type	Description
options	`GetFileTypeInformationOptions`	Configuration object containing the input source (file or string) and the desired level of type inference.

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.

Returns:

Promise<FileTypeInformation | null>

A promise that resolves to a FileTypeInformation object if the input was parsed successfully. Otherwise, it resolves to null.

`serializeTypeInformation(fileTypeinformation)`

Parameter	Type	Description
fileTypeinformation	`FileTypeInformation`	`FileTypeInformation` object to serialize.

Used for testing purposes, maps Sets and Maps to Arrays and returns FileTypeInformationSerialized object which can be written to a JSON.

Returns:

FileTypeInformationSerialized

a FileTypeInformationSerialized object.

TypeScript generation

`generateConciseTsInterface(fileTypeInformation)`

Parameter	Type	Description
fileTypeInformation	`FileTypeInformation`	The abstracted type information of an Expo module.

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.

Returns:

Promise<{
  moduleTypescriptInterfaceFileContent: string, 
  volatileGeneratedFileContent: string
}>

A promise that resolves to an object containing the string contents for both the volatile generated file and the stable TypeScript interface file.

`generateFullTsInterface(fileTypeInformation)`

Parameter	Type	Description
fileTypeInformation	`FileTypeInformation`	The abstracted type information of an Expo module.

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.

Returns:

Promise<{
  indexFile: OutputFile, 
  moduleNativeFile: OutputFile, 
  moduleTypesFile: OutputFile, 
  moduleViewsFiles: OutputFile[]
} | null>

A promise that resolves to an object containing the string contents for all of the generated files or null if the generation has failed.

`generateJSXIntrinsicsFileContent(fileTypeInformation)`

Parameter	Type	Description
fileTypeInformation	`FileTypeInformation`	The abstracted type information of an Expo module.

Generates the TypeScript string content for a native View's type declaration file which mounts the View props on the global JSXIntrinsics.

Returns:

Promise<string | null>

A promise that resolves to a string containing the TypeScript declaration file content or null if the generation has failed.

`generateModuleTypesFileContent(fileTypeInformation)`

Parameter	Type	Description
fileTypeInformation	`FileTypeInformation`	The abstracted type information of an Expo module.

Generates the TypeScript string content for a native module type declaration file.

Returns:

Promise<string | null>

A promise that resolves to a string containing the TypeScript module declaration file content or null if the generation has failed.

`generateViewTypesFileContent(fileTypeInformation)`

Parameter	Type	Description
fileTypeInformation	`FileTypeInformation`	The abstracted type information of an Expo module.

Generates the TypeScript string content for a native View's type declaration file.

Returns:

Promise<string | null>

A promise that resolves to a string containing the TypeScript declaration file content or null if the generation has failed.

Mock generation

`generateMocks(files, outputLanguage)`

Parameter	Type	Description
files	`FileTypeInformation[]`	A list of `FileTypeInformation` objects with generated type information for multiple modules
outputLanguage(optional)	`'typescript' \| 'javascript'`	the language to emit the mocks in Default:`'javascript'`

This function generates JavaScript/TypeScript mocks for each provided FileTypeInformation object.

Returns:

Promise<void>

nothing

`getAllExpoModulesInWorkingDirectory()`

Returns:

Promise<FileTypeInformation[]>

Component

`withPreparedSingleFile`

Type: React.Element<GetFileTypeInformationOptions>

Types

`AnonymousType`

Literal type: union

Represents an anonymous type, a one that is not named instead written directly in the code, such as inline generics, arrays, or optionals.

Acceptable values are: ParametrizedType | SumType | OptionalType | DictionaryType | ArrayType

`Argument`

Represents an argument passed to a function or constructor.

Property	Type	Description
name	`string \| undefined`	-
type	`Type`	-

`ArrayType`

Type: 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.

`ClassDeclaration`

Represents a DSL native class declaration.

Type: DefinitionOffset extended by:

Property	Type	Description
asyncMethods	`FunctionDeclaration[]`	-
constructor	`ConstructorDeclaration \| null`	-
methods	`FunctionDeclaration[]`	-
name	`string`	-
properties	`PropertyDeclaration[]`	-

`ConstantDeclaration`

Represents a DSL constant declaration.

Type: DefinitionOffset extended by:

Property	Type	Description
name	`string`	-
type	`Type`	-

`ConstructorDeclaration`

Represents a DSL class constructor declaration.

Type: DefinitionOffset extended by:

Property	Type	Description
arguments	`Argument[]`	-

`DefinitionOffset`

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, maintaining the same ordering as in original file.

Property	Type	Description
definitionOffset	`number`	-

`DictionaryType`

Represents a dictionary type, defining the explicit types for its keys and values.

Property	Type	Description
key	`Type`	-
value	`Type`	-

`EnumCase`

Represents a single case inside an enum declaration.

Type: string

`EnumType`

Represents an enum type, containing its name and all associated cases.

Property	Type	Description
cases	`EnumCase[]`	-
name	`string`	-
stringBacked	`boolean`	-

`EventDeclaration`

Represents a DSL event declaration.

Type: string

`Field`

Type: Argument

Represents a single field within a record or a struct.

`FileInputOption`

Defines an input option for extracting type information from a set of physical files.

Property	Type	Description
inputFileAbsolutePaths	`string[]`	-
type	`'file'`	-

`FileTypeInformation`

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).

Property	Type	Description
declaredTypeIdentifiers	`Set<string>`	-
enums	`EnumType[]`	-
inferredTypeParametersCount	`Map<string, number>`	-
moduleClasses	`ModuleClassDeclaration[]`	-
records	`RecordType[]`	-
typeIdentifierDefinitionMap	`TypeIdentifierDefinitionMap`	-
usedTypeIdentifiers	`Set<string>`	-

`FileTypeInformationSerialized`

Serialized version of the FileTypeInformation, suitable for JSON storage or testing environments.

Property	Type	Description
declaredTypeIdentifiersList	`string[]`	-
enums	`EnumType[]`	-
inferredTypeParametersCountList	`undefined`	-
moduleClasses	`ModuleClassDeclaration[]`	-
records	`RecordType[]`	-
typeIdentifierDefinitionList	`TypeIdentifierDefinitionList`	-
usedTypeIdentifiersList	`string[]`	-

`FunctionDeclaration`

Represents a DSL function declaration.

Type: DefinitionOffset extended by:

Property	Type	Description
arguments	`Argument[]`	-
isStatic	`boolean`	-
name	`string`	-
parameters	`Type[]`	-
returnType	`Type`	-

`GetFileTypeInformationOptions`

Options specifying the input source and inference level for retrieving type information.

Property	Type	Description
input	`StringInputOption \| FileInputOption`	The input source, provided either as a direct string or a file path.
mapUnicodeCharacters	`boolean`	An option to map unicode code points to ASCII strings to fix underlying SourceKit issue.
typeInference(optional)	`TypeInferenceOption`	The desired level of type inference. Defaults to PREPROCESS_AND_INFERENCE if omitted.

`IdentifierDefinition`

Represents a definition of an identifier.

Property	Type	Description
definition	`string \| RecordType \| EnumType \| ClassDeclaration`	-
kind	`IdentifierKind`	-

`ModuleClassDeclaration`

Represents a DSL module declaration.

Type: DefinitionOffset extended by:

Property	Type	Description
asyncFunctions	`FunctionDeclaration[]`	-
classes	`ClassDeclaration[]`	-
constants	`ConstantDeclaration[]`	-
constructor	`ConstructorDeclaration \| null`	-
events	`EventDeclaration[]`	-
functions	`FunctionDeclaration[]`	-
name	`string`	-
properties	`PropertyDeclaration[]`	-
props	`PropDeclaration[]`	-
views	`ViewDeclaration[]`	-

`OptionalType`

Type: 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.

`OutputFile`

A helper type which contains the generated file content and name.

Property	Type	Description
content	`string`	-
name	`string`	-

`ParametrizedType`

Represents a parametrized type, that is a generic type with specified parameters e.g. Map<string, number>.

Property	Type	Description
name	`TypeIdentifier`	-
types	`Type[]`	-

`PropDeclaration`

Represents a DSL prop declaration.

Type: DefinitionOffset extended by:

Property	Type	Description
arguments	`Argument[]`	-
name	`string`	-

`PropertyDeclaration`

Type: ConstantDeclaration

Represents a DSL property declaration.

`RecordType`

Represents a struct or dictionary-like record consisting of named fields.

Property	Type	Description
fields	`Field[]`	-
name	`string`	-

`StringInputOption`

Defines an input option for extracting type information directly from a raw string of source code.

Property	Type	Description
fileContent	`string`	-
language	`'Swift'`	-
type	`'string'`	-

`SumType`

Represents a union or a sum type where a value can be one of several different types.

Property	Type	Description
types	`Type[]`	-

`Type`

Represents an abstract type node.

Property	Type	Description
kind	`TypeKind`	-
type	`BasicType \| TypeIdentifier \| AnonymousType`	-

`TypeIdentifier`

Represents a type identifier as a string reference.

Type: string

`TypeIdentifierDefinitionList`

Type: undefined

Serialized version of the TypeIdentifierDefinitionMap.

`TypeIdentifierDefinitionMap`

Type: Map<string, IdentifierDefinition>

Maps type identifier strings to their definition objects.

`ViewDeclaration`

Type: ModuleClassDeclaration

Represents a DSL view declaration.

Enums

`BasicType`

Represents a basic type that is not user defined.

`ANY`

BasicType.ANY ＝ 0

`STRING`

BasicType.STRING ＝ 1

`NUMBER`

BasicType.NUMBER ＝ 2

`BOOLEAN`

BasicType.BOOLEAN ＝ 3

`VOID`

BasicType.VOID ＝ 4

`UNDEFINED`

BasicType.UNDEFINED ＝ 5

`UNRESOLVED`

BasicType.UNRESOLVED ＝ 6

Represents a type that couldn't be resolved

`IdentifierKind`

Represents the kind of a parsed identifier from a native file.

`BASIC`

IdentifierKind.BASIC ＝ 0

`ENUM`

IdentifierKind.ENUM ＝ 1

`RECORD`

IdentifierKind.RECORD ＝ 2

`CLASS`

IdentifierKind.CLASS ＝ 3

`TypeInferenceOption`

Defines the level of type inference to apply when extracting type information.

Note: In case where type inference is on, it may take more than twice the time to compute the type information.

`NO_INFERENCE`

TypeInferenceOption.NO_INFERENCE ＝ 0

No type inference will be performed.

`SIMPLE_INFERENCE`

TypeInferenceOption.SIMPLE_INFERENCE ＝ 1

Basic type inference will be applied.

`PREPROCESS_AND_INFERENCE`

TypeInferenceOption.PREPROCESS_AND_INFERENCE ＝ 2

Preprocesses the file by injecting returns to extract more type info from sourcekitten.

`TypeKind`

Categorizes the type node within the abstract syntax tree.

`BASIC`

TypeKind.BASIC ＝ 0

`IDENTIFIER`

TypeKind.IDENTIFIER ＝ 1

`SUM`

TypeKind.SUM ＝ 2

`PARAMETRIZED`

TypeKind.PARAMETRIZED ＝ 3

`OPTIONAL`

TypeKind.OPTIONAL ＝ 4

`ARRAY`

TypeKind.ARRAY ＝ 5

`DICTIONARY`

TypeKind.DICTIONARY ＝ 6

Swift 解析器的限制

🌐 Swift parser limitations

expo-type-information 库使用 sourcekitten 来解析 Swift 文件。解析 Swift 文件是一项复杂的任务，目前并不是所有功能都已实现。

关于当前版本解析 Swift 文件的已知问题

嵌套类将不会被完全解析。

Sourcekitten 对解析嵌套闭包有一个限制，因此你模块中定义的类可能无法被完全解析。这就是为什么如果模块中有一个 DSL Class，其方法的返回类型会是 unresolved 的原因。
返回类型解析，PREPROCESS_AND_INFERENCE 推断选项。

当闭包的返回类型没有明确提供时，工具需要推断它。在 sourcekitten 中的一种方法是，当存在 return identifier 语句时，我们可以询问 identifier 的类型。第三种推断选项，PREPROCESS_AND_INFERENCE，会重写文件，使得对于每个 return expression 语句，都插入一个新的 let return_expression = expression; return return_expression;，以便我们可以询问标识符的类型。众所周知，重写有时会出现问题（主要是因为字符串和注释），所以它可能并不总是有效。当前也没有办法解析没有 return 的返回，当返回表达式是闭包的尾表达式时。
不支持的 Expo 模块 DSL 声明。

并非所有的 DSL 声明现在都能被解析，并且有些在每种上下文中都不能解析。例如，Events 在 View 内可以解析，但在模块定义中不能解析。
使用 Unicode 字符会破坏 sourcekitten 偏移量。

支持的 Expo 模块 DSL 声明

🌐 Supported Expo modules DSL declarations

功能	说明和限制
Expo DSL 声明	支持解析: `AsyncFunction`、`Constant`、`Constructor`、`Events`、`Function`、`Name`、`Prop`、`Property` 和 `View`。
Swift `struct` & `class`	必须遵循 `Record` 协议。只有标记了 `@Field` 注解的属性会被解析。
Swift `enum`	支持基本情况。目前不解析与枚举成员关联的值。