nodejs-driver icon indicating copy to clipboard operation
nodejs-driver copied to clipboard

NODEJS-680: Update and Automate TypeScript Support

Open SiyaoIsHiding opened this issue 7 months ago • 4 comments

Massive refactoring. Changes can be broken down into the following parts:

  1. Rename files from .js to .ts.
  2. Update import/export syntax to ESM syntax - some index files have to export both named and default to be compatible with the previous require behavior.
  3. Refactor ES5 style classes to ES6 style classes
  4. Cleaning TypeScript errors and eslint errors in core
  5. Fix API exposure - My rationale is: if an API was exposed in previous .d.ts, it's supposed to be exposed. If it has documentation on how a user should use it, it's supposed to be exposed. There are some inconsistencies. Please search //TODO to find them.
  6. Make sure tests pass and set up CI: Replace the use of proxyquire to sinon. Add rollup for bundle, api-extractor to encapusulate, and eslint for linting.

We need to discuss:

  1. Please search //TODO to find the places where I am not sure what to do. Some are breaking changes.
  2. How can we maintain backward compatibility of the dotted type names, like cassandra.errors.DriverError? In the current master branch, this is the only way to use types:
import cassandra from 'cassandra-driver';
// ...
client.execute(query, (err: cassandra.errors.DriverError, result: cassandra.types.ResultSet) => {});

Or, with one level down imports

import {errors, types } from 'cassandra-driver';
 client.execute(query, (err: errors.DriverError, result: types.ResultSet) => {});

However, the TypeScript default way, also the way how other libraries expose the types, is to flatten all exported classes.

import {DriverError, ResultSet } from 'cassandra-driver';
 client.execute(query, (err: DriverError, result: ResultSet) => {});

Now how can we maintain backward compatibility to the previous dotted ones? The only workaround I can find is to append such things at the end of our dist/cassandra-driver-public.d.ts

export namespace errors{
    export type DriverError = InstanceType<typeof DriverError>;
}

This is the last step of the bundle script in this PR. 3. How do we maintain backward compatibility of import x = y.z syntax?

import { mapping } from "../../../index";
import Mapper = mapping.Mapper;
const mapper: Mapper = new Mapper();

This currently will raise an error Mapper is a type, but used as a value. I cannot see a solution.

  1. What do we want to do with our documentation? Should we update all code snippets into TypeScript?

SiyaoIsHiding avatar Apr 29 '25 00:04 SiyaoIsHiding

I forgot Travis CI. Will fix.

SiyaoIsHiding avatar Apr 29 '25 01:04 SiyaoIsHiding

Contact doc team and see what we should do with JSdoc type definitions v.s. TypeScript type definitions.

SiyaoIsHiding avatar May 13 '25 16:05 SiyaoIsHiding

Minimal reproducible case for import x = y.z error

SiyaoIsHiding avatar May 13 '25 16:05 SiyaoIsHiding

Optimize the pipeline to only distribute necessary files.

SiyaoIsHiding avatar May 13 '25 17:05 SiyaoIsHiding