Best practices for structuring TypeScript type declarations for a function module containing numerous private classes

Question

Best practices for structuring TypeScript type declarations for a function module containing numerous private classes

Currently, I am in the process of creating type definitions for a library called fessonia. This task is not new to me, but this particular library has a different organization compared to others I have worked with before, presenting a unique challenge.

The main function in this library's index.js file is concise:

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;

This function exports an object containing classes, with getFessonia being the only public interface according to the library documentation. Despite other classes being accessible directly, it is recommended to only use getFessonia due to potential configuration issues.

I aim for the type definitions to advocate best practices when utilizing this library. This means excluding methods flagged as @private or not intended for external usage. For instance, proper types should enable downstream developers to declare variables with specific types:

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

It is essential for declaration files to align with the library structure. As per the official recommendation.

My current approach involves creating separate .d.ts files for each required .js file to generate coherent type definitions. These files are then consolidated into index.d.ts, enhancing clarity and usability for developers.

As I progress, some concerns arise:

Do I need to provide a definition for the getConfig function, considering its limitation on direct usage? Should I export the Config interface directly instead and re-export it from index.d.ts? Similarly, how do I manage excessive aliasing under the getFessonia namespace?
Re-exporting within namespaces can be tedious and less elegant.
The potential nesting under getFessonia could lead to complexity in defining arguments and class shapes.
The organizational structure, such as using the FFmpeg namespace, might need refinement.

Your commitment to reading until the end is appreciated! While there may not be a definitive solution, I am open to exploring different approaches taken by others and welcome recommendations for improvement. Thank you!

typescript type-definition

Answer 1

Answer №1

@alex-wayne's insight was a game-changer for me. I am grateful.

I realized that I had been mistakenly assuming that the library's use of default exports prevented me from exporting other entities in my type definitions. Perhaps lack of sleep played a role in this oversight!

In addition to exporting the function getFessonia as a default, I also exported an interface Fessonia to define the return value and a namespace with the same name (more on TypeScript's combining behavior) to provide types for getFessonia's options and various other entities from the library. Here is how my updated index.d.ts file looks:

(import statements omitted for brevity)
/** 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;
}

(import statements for types only)
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,
    };
}

My approach for defining the classes within the Fessonia object involved creating individual type definitions for each class and exporting them without including private members. If a class method had parameters with complex types, I would define those types separately and put them in a namespace with the same name as the class, like so:

// 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;
}

By re-exporting the types at the end of index.d.ts, I was able to write code like the following downstream:

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

Although the revised structure may not be dramatically different from the original, it does feel like an enhancement. I kept the organization simple and consistent with the existing codebase, introducing the Fessonia namespace where necessary. Overall, the readability has improved.

You can view my initial attempt at typing this library on GitHub. Thank you to all who provided feedback and encouraged me to think outside the box.

Answer 2

@alex-wayne's insight was a game-changer for me. I am grateful.

I realized that I had been mistakenly assuming that the library's use of default exports prevented me from exporting other entities in my type definitions. Perhaps lack of sleep played a role in this oversight!

In addition to exporting the function getFessonia as a default, I also exported an interface Fessonia to define the return value and a namespace with the same name (more on TypeScript's combining behavior) to provide types for getFessonia's options and various other entities from the library. Here is how my updated index.d.ts file looks:

(import statements omitted for brevity)
/** 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;
}

(import statements for types only)
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,
    };
}

My approach for defining the classes within the Fessonia object involved creating individual type definitions for each class and exporting them without including private members. If a class method had parameters with complex types, I would define those types separately and put them in a namespace with the same name as the class, like so:

// 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;
}

By re-exporting the types at the end of index.d.ts, I was able to write code like the following downstream:

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

Although the revised structure may not be dramatically different from the original, it does feel like an enhancement. I kept the organization simple and consistent with the existing codebase, introducing the Fessonia namespace where necessary. Overall, the readability has improved.

You can view my initial attempt at typing this library on GitHub. Thank you to all who provided feedback and encouraged me to think outside the box.

Best practices for structuring TypeScript type declarations for a function module containing numerous private classes

Answer №1

Similar questions

Implementing Dynamic FormControl Values within FormGroup in Angular: A Step-by-Step Guide

Creating a rootscope variable within an .ASPX file

Unit Testing AngularJS Configuration in TypeScript with Jasmine

typescript provides an asynchronous recursive mapping function that allows for changing parent data starting from the leaf node

How to implement a material chiplist in Angular 8 using formGroup

How to transfer an object between sibling components in Angular 4

Retrieve data from a table within an Angular component

Error Encountered (TypeError): Unable to access attributes of undefined (attempting to read 'appendChild')

Enter the quiz that starts counting down as soon as you open it

Bringing in a module that enhances a class

Leverage a custom server (such as NestJS) within NextJS to dynamically render targeted pages

What is the best way to define the type of an object in TypeScript when passing it to a function

Issue: Map container not located when implementing a leaflet map with Angular

Preventing going back to a previous step or disabling a step within the CDK Stepper functionality

Can an Angular Component be displayed using a Serverless function like Lambda on AWS?

A different approach to fixing the error "Uncaught (in promise) TypeError: fs.writeFile is not a function" in TensorFlow.js when running on Chrome

Issue with data not being assigned to TypeScript class variable

Firefox validation doesn't prevent users from entering invalid input

Filter a data array using a two-dimensional filter array that may change dynamically

Styling <Link> component with styled-components: A step-by-step guide