Specification for TypeScript Import and Export Notation

Overview

This specification defines a notation format for representing TypeScript imports and exports. It is designed to be concise, flexible, and easily understandable, suitable for use in various contexts including configuration files, command-line interfaces, and documentation.

Format Design

Basic Structure

• Imports and Exports: Use - to start import declarations and ~ to start export declarations.
• Namespace Imports: Double bangs !! indicate namespace imports (e.g., * as name).
• Type-only Imports/Exports: Double tilde ~~ for type-only exports and double dash -- for type-only imports.
• Grouping: Use parentheses () to group the module specifier with its imports or exports.

Detailed Syntax:

• Namespace Import: -moduleName(!!alias)
  • Example: -transferables(!!transferables)
• Default Import: -moduleName(alias)
  • Example: -spring-easing(transfer)
• Named Import/Export: -moduleName(alias1!alias2)
  • alias1 is the original name, and alias2 is the local name.
  • Example: -spring-easing(SpringEasing!SE)
• Type Import: --moduleName(TypeName)
  • Example: --spring-easing(SpringEasingType)
• Type Export: ~~moduleName(TypeName)
  • Example: ~~spring-easing(SpringEasingType)
• Namespace Export: ~moduleName(*!alias)
  • Example: ~transferables(*!ttf)
• Aggregate Exports: moduleName(!exported1~type*!exported2~type*exported3!alias)
  • Combines multiple export forms, including renaming and type exports.
  • Example: spring-easing(!SpringEasing~type*!SpringFrame~type*SpringOutFrame!SpringOutFrameType~SpringOutFrame!Spring)

References

This format takes inspiration from the TypeScript Handbook on Modules (TypeScript Modules) and ECMAScript modules specifications. It aims to provide an analogous notation that encapsulates the flexibility of TypeScript's rich import/export syntax.

Test Cases

1. Namespace Import and Export

   • Input: -lodash(!!_)~d3(*!d3)
   • Expected Interpretation: Import all of lodash as _ and export all of d3 as d3.

2. Complex Aggregate Export

   • Input: ~utils(!combine~type*!merge~type*select!selectAs)
   • Expected Interpretation: Export combine and merge as types, and select as selectAs from the "utils" module.

3. Type-only Import and Export

   • Input: --colors(ColorType)~~animations(AnimationType)
   • Expected Interpretation: Import ColorType from "colors" module and export AnimationType from "animations" module as a type.

4. Mixed Import Types

   • Input: -rxjs(observable!Observable)--rxjs(operatorType)
   • Expected Interpretation: Import observable as Observable and import operatorType as a type from "rxjs".

5. Default and Named Imports

   • Input: -axios(default!axios)-axios(config!AxiosConfig)
   • Expected Interpretation: Import the default export of "axios" as axios and config as AxiosConfig.

Revised Specification for TypeScript Import and Export Notation (CTIE Format) with Emphasis on Type-Only Imports and Exports

Overview

This updated specification for the CTIE format places a stronger emphasis on promoting type-only imports and exports where applicable. The goal is to encourage the separation of type information from runtime code, enhancing code optimization and clarity. This approach aligns with modern TypeScript practices that aim to keep runtime code and type definitions distinctly managed, thus facilitating better build optimization and cleaner code separation.

Format Design Modifications

Basic Structure Adjustments

• Type-Only Imports and Exports Preference: Whenever possible, type-only imports and exports should be used to separate type definitions from runtime imports/exports.
• Syntax Highlighting for Types: -- is used for type-only imports and ~~ for type-only exports to distinctly separate them from runtime code interactions.

Detailed Syntax:

• Type Import: --moduleName(TypeName)
  • Example: --react(ReactComponentType)
• Type Export: ~~moduleName(TypeName)
  • Example: ~~utils(UtilityTypes)

Examples in the Specification for TypeScript Import and Export Notation (CTIE Format)

To help clarify how the CTIE notation maps to TypeScript code, the following examples illustrate the notation alongside the equivalent TypeScript code. This section aims to demonstrate practical usage scenarios and ensure the specification's applicability and ease of understanding.

Example 1: Simple Imports and Exports

CTIE Format:

-transferables(!!transferables)~lodash(*!_)

TypeScript Code:

import * as transferables from "transferables";
export * as _ from "lodash";

Description:

• The CTIE notation -transferables(!!transferables) indicates importing all of "transferables" as an alias transferables.
• The notation ~lodash(*!_) indicates exporting all of "lodash" under the alias _.

Example 2: Default and Named Import

CTIE Format:

-react(default!React)-react-dom(ReactDOM)

TypeScript Code:

import React from "react";
import ReactDOM from "react-dom";

Description:

• default!React specifies importing the default export from "react" and naming it React.
• ReactDOM without any prefixes implies importing the default export as ReactDOM.

Example 3: Complex Exports

CTIE Format:

~utils(!combine~type*!merge~type*select!selectAs)

TypeScript Code:

export { combine, type merge, select as selectAs } from "utils";

Description:

• This exports combine as a regular export, merge as a type, and renames select to selectAs.

Example 4: Type-only Import and Export

CTIE Format:

--colors(ColorType)~~animations(AnimationType)

TypeScript Code:

import type { ColorType } from "colors";
export type { AnimationType } from "animations";

Description:

• The --colors(ColorType) notation specifies importing ColorType as a type-only import.
• The ~~animations(AnimationType) notation specifies exporting AnimationType as a type-only export.

Example 5: Mixed Import Types and Aggregated Exports

CTIE Format:

-rxjs(observable!Observable)--rxjs(operatorType)~rxjs(!Subject~type*!BehaviorSubject)

TypeScript Code:

import { observable as Observable, type operatorType } from "rxjs";
export { Subject, type BehaviorSubject } from "rxjs";

Description:

• Import observable from "rxjs" and rename it to Observable.
• Import operatorType as a type-only import.
• Export Subject and BehaviorSubject as a type from "rxjs".

Policy on Type-Only and Runtime Code

1. Prefer Type-Only Imports/Exports: When both type and runtime values are available from a module, prefer using type-only imports/exports unless the runtime value is explicitly required.

2. Enforce Type-Only Where Applicable: In scenarios where a type is only used for type checking (e.g., interfaces, types), enforce the usage of type-only imports and exports.

3. Mixed Imports/Exports Handling: For modules providing both types and values, separate imports and exports clearly using the designated syntax for types and values.

Updated Examples

Example 1: Preferred Type-Only Import

CTIE Format:

--material-ui(styles)

TypeScript Code:

import type { styles } from "material-ui";

Description:

• This imports styles as a type-only import, emphasizing that it's used for type checking and not included in the runtime bundle.

Example 2: Preferred Type-Only Export

CTIE Format:

~~helpers(APIResponseTypes)

TypeScript Code:

export type { APIResponseTypes } from "helpers";

Description:

• This exports APIResponseTypes as a type-only export, making it clear that these are only for type checking.

Example 3: Mixed Type and Value Import

CTIE Format:

-react(React)--react(ReactComponentProps)

TypeScript Code:

import React from "react";
import type { ReactComponentProps } from "react";

Description:

• Regular import for the React object, and a type-only import for ReactComponentProps.

These examples are designed to show the versatility and expressiveness of the CTIE notation in handling various import and export scenarios. They demonstrate how a single line of CTIE notation can represent complex TypeScript module interactions, facilitating a clear, concise, and scalable approach to managing TypeScript imports and exports.

Recommendations to Reduce Learning Curve

1. Comprehensive Documentation: Provide detailed documentation with examples for each type of import and export.
2. Visual Aids: Include diagrams or flowcharts in documentation to visualize how the notation maps to TypeScript code.
3. Tools and Linters: Develop tools or extend existing linters to validate and auto-correct the notation as per the specification.
4. Interactive Learning Modules: Offer interactive tutorials or a playground to experiment with the notation and see real-time TypeScript code generation.

Recommendations for Implementation

1. Tooling Support: Enhance tooling to recognize and differentiate between type-only and regular imports/exports automatically, suggesting adjustments when possible.
2. Linting and Code Review: Integrate lint rules that favor type-only imports and exports during code reviews to enforce this practice.
3. Documentation and Training: Provide detailed documentation and training materials that emphasize the importance and benefits of using type-only imports and exports.

This format aims to standardize the representation of module import and export operations in a compact and expressive manner, facilitating ease of use across different platforms and tools.