问题描述
我正在为一个名为 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);
中设置的配置尚未设置,并且可能会导致错误). - 类型定义应该很有用。下游开发人员应该能够将类型分配给他们的变量à la:
.d.ts
- 声明文件的布局应该反映库的布局。每个official recommendation。
到目前为止,我采取的方法是为创建有用类型定义所需的每个 .js
文件创建 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,FFmpegOutput } = getFessonia(); // note the deep nesting const outputoptions: getFessonia.FFmpeg.Output.Options = { /* some stuff */ }; const output = new FFmpegOutput('some/path',outputoptions);
的参数映射,因此下游代码可能最终看起来像:
getFessonia
- 将
FFmpegOutput
的参数和FFmpeg
的形状定义为同级不是很直观。 - 出于组织/命名冲突避免的原因,我正在创建
<div class="tags"> {posts.map(post => [...new Set(post.frontmatter.tags)].map(tag => ( <Link key={tag + `tag`} to={`/tags/${kebabCase(tag)}/`} className="tag is light" > {tag} </Link> )) )} </div>
命名空间。
你坚持到了最后!感谢您阅读到这里。虽然我怀疑没有一个“正确”的答案,但我期待阅读其他人采用的方法,并且很高兴被指出我可以通过示例学习的文章或相关代码存储库。谢谢!
解决方法
@alex-wayne 的评论帮助我重置了大脑。谢谢。
出于某种原因,我在编写类型定义时好像库使用默认导出意味着我不能从我的 .d.ts
文件中导出其他内容。可能是睡眠不足!
无论如何,除了默认导出函数 getFessonia
之外,我最终导出了一个接口 Fessonia
来描述返回值以及同名的命名空间 (more on TypeScript's combining behavior)为 getFessonia
的选项以及库提供的各种其他实体提供类型。 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。
感谢所有评论并让我产生不同想法的人。