如何为具有大量私有类的功能模块组织 Typescript 类型定义？

Question

我正在为我不拥有的名为 fessonia 的库编写类型定义。我有一些这样做的经验，但是这个库的组织方式与我合作过的其他库不同，我不知道如何处理它。

这个库的index.js 很小：

const getFessonia = (opts = {}) => {
  require('./lib/util/config')(opts);
  const Fessonia = {
    FFmpegCommand: require('./lib/ffmpeg_command'),
    FFmpegInput: require('./lib/ffmpeg_input'),
    FFmpegOutput: require('./lib/ffmpeg_output'),
    FilterNode: require('./lib/filter_node'),
    FilterChain: require('./lib/filter_chain')
  };
  return Fessonia;
}

module.exports = getFessonia;

它导出一个返回对象的函数，该对象的每个成员都是一个类。 （到目前为止，我在 lib 中遇到的每个文件都使用默认导出。）我从 module function template 开始，但我很难在我的一些指导原则之间找到和谐：

• 类型定义应该促进使用这个库的最佳实践。我的意思是我不会费心为标记为 @private 或不打算/不推荐的方法创建定义供外用。根据库文档，getFessonia 是该库的唯一公共接口。虽然没有什么可以阻止开发人员直接导入 FFmpegCommand，但不应该这样做（因为，例如，在 getFessonia 中设置的配置不会被设置，并且可能会导致错误）。李>
• 类型定义应该很有用。下游开发人员应该能够为他们的变量分配类型：

import getFessonia from '@tedconf/fessonia';
// note the type assignment
const config: getFessonia.ConfigOpts = {
    debug: true,
};
const { FFmpegCommand, FFmpegInput, FFmpegOutput } = getFessonia(config);

• 声明文件的布局应反映库的布局。根据official recommendation。

到目前为止，我采用的方法是为每个 .js 文件创建有用的类型定义所需的 .d.ts 文件，然后将它们导入 index.d.ts 并根据需要在 getFessonia 命名空间中重新导出.例如，为了为opts 参数提供类型定义，我需要阅读lib/util/config，它有一个默认导出getConfig。它的类型文件最终看起来像这样：

import getLogger from './logger';

export = getConfig;

/**
 * Get the config object, optionally updated with new options
 */
declare function getConfig(options?: Partial<getConfig.Config>): getConfig.Config;

declare namespace getConfig {
    export interface Config {
      ffmpeg_bin: string;
      ffprobe_bin: string;
      debug: boolean;
      log_warnings: boolean;
      logger: getLogger.Logger;
    }
}

...我在index.d.ts 中这样使用它：

import getConfig from './lib/util/config';

export = getFessonia;

/**
 * Main function interface to the library. Returns object of classes when called.
 */
declare function getFessonia(opts?: Partial<getFessonia.ConfigOpts>): getFessonia.Fessonia;

declare namespace getFessonia {
    export interface Fessonia {
        // TODO
        FFmpegCommand: any;
        FFmpegInput: any;
        FFmpegOutput: any;
        FilterNode: any;
        FilterChain: any;
    }
    // note I've just aliased and re-exported this
    export type ConfigOpts = Partial<getConfig.Config>;
}

我认为我可能走错路的原因：

• 我认为我不需要定义函数getConfig，尤其是因为我不想推广它的直接使用。 lib/util/config 有默认导出是否重要？我是否应该直接导出Config 接口并从index.d.ts 重新导出？或者我可能会删除函数定义并将Config接口保留在命名空间下；这样，如果getConfig 将来成为公共函数，我可以添加函数的定义。
• 在 getFessonia 命名空间下重新导出很乏味，而且不是特别优雅。
• 我可能会在getFessonia 下得到很多嵌套（和别名）。例如，FFmpegOutput 的构造函数接受一个参数，该参数实际上只是内部类 FFmpegOption 的参数映射，因此下游代码可能最终看起来像这样：

import getFessonia from '@tedconf/fessonia';

const { FFmpegCommand, FFmpegInput, FFmpegOutput } = getFessonia();
// note the deep nesting
const outputOptions: getFessonia.FFmpeg.Output.Options = { /* some stuff */ };
const output = new FFmpegOutput('some/path', outputOptions);

• 将getFessonia 的参数定义和FFmpegOutput 的形状定义为兄弟关系不是很直观。
• 出于组织/命名冲突避免原因，我正在编造 FFmpeg 命名空间。

你做到了！感谢您阅读本文。虽然我怀疑没有一个“正确”的答案，但我期待阅读其他人采用的方法，我很高兴有人指出我可以通过示例学习的文章或相关代码存储库。谢谢！

Answer 1

@alex-wayne 的评论帮助我重置了大脑。谢谢。

出于某种原因，我正在编写类型定义，就好像库对默认导出的使用意味着我也无法从我的 .d.ts 文件中导出其他内容。可能是睡眠不足！

无论如何，除了默认导出函数getFessonia之外，我最终导出了一个接口Fessonia来描述返回值以及一个同名的命名空间（more on TypeScript's combining behavior）来为@987654327提供类型@ 的选项以及库提供的各种其他实体。 index.d.ts 最终看起来像：

import { FessoniaConfig } from './lib/util/config';
import FFmpegCommand from './lib/ffmpeg_command';
import FFmpegInput from './lib/ffmpeg_input';
import FFmpegOutput from './lib/ffmpeg_output';
import FilterChain from './lib/filter_chain';
import FilterNode from './lib/filter_node';

/** Main function interface to the library. Returns object of classes when called. */
export default function getFessonia(opts?: Partial<Fessonia.ConfigOpts>): Fessonia;

export interface Fessonia {
  FFmpegCommand: typeof FFmpegCommand;
  FFmpegInput: typeof FFmpegInput;
  FFmpegOutput: typeof FFmpegOutput;
  FilterChain: typeof FilterChain;
  FilterNode: typeof FilterNode;
}

// re-export only types (i.e., not constructors) to prevent direct instantiation
import type FFmpegCommandType from './lib/ffmpeg_command';
import type FFmpegError from './lib/ffmpeg_error';
import type FFmpegInputType from './lib/ffmpeg_input';
import type FFmpegOutputType from './lib/ffmpeg_output';
import type FilterNodeType from './lib/filter_node';
import type FilterChainType from './lib/filter_chain';
export namespace Fessonia {
    export type ConfigOpts = Partial<FessoniaConfig>;

    export {
      FFmpegCommandType as FFmpegCommand,
      FFmpegError,
      FFmpegInputType as FFmpegInput,
      FFmpegOutputType as FFmpegOutput,
      FilterChainType as FilterChain,
      FilterNodeType as FilterNode,
    };
}

对于属于Fessonia 对象的类，我的一般方法是为每个类创建一个类型定义（省略私有成员）并将其导出。如果类函数具有复杂类型的参数，我会为它们创建定义并将它们导出到与类同名的命名空间中，例如：

// abridged version of types/lib/ffmpeg_input.d.ts
export default FFmpegInput;

declare class FFmpegInput {
    constructor(url: FFmpegInput.UrlParam, options?: FFmpegInput.Options);
}

declare namespace FFmpegInput {
    export type Options = Map<string, FFmpegOption.OptionValue> | { [key: string]: FFmpegOption.OptionValue };
    export type UrlParam = string | FilterNode | FilterChain | FilterGraph;
}

由于index.d.ts底部的类型重新导出，这个下游代码成为可能：

import getFessonia, { Fessonia } from '@tedconf/fessonia';

const { FFmpegCommand, FFmpegInput, FFmpegOutput } = getFessonia();
// note the type assignment
const outputOptions: Fessonia.FFmpegOutput.Options = { /* some stuff */ };
const output = new FFmpegOutput('some/path', outputOptions);
const cmd = new FFmpegCommand(commandOpts);

虽然这与我最初的想法并没有太大的不同，但它确实感觉像是一种改进。我不必发明太多新的组织结构；类型名称与代码库的结构一致（添加了Fessonia 命名空间）。而且它是可读的。

我第一次输入这个库是available on GitHub。

感谢所有发表评论并让我产生不同想法的人。