npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@eclipse-scout/migrate

v24.2.16

Published

TypeScript migration module

Downloads

192

Readme

Eclipse Scout - Migrate

Migration tool to help migrating the JavaScript/TypeScript code from one Scout release to another.

Usage

To set up the tool, do the following:

  • Open the package.json of your ui module (e.g. your.project.ui.html).
  • Add a devDependency to @eclipse-scout/migrate.
  • Run pnpm install to install the new dependency.
  • Do the required migration as described in the following chapters.
  • When you are finished, remove the added dependency and migration script from you package.json.
{
  "devDependencies": {
    "@eclipse-scout/migrate": "~24.2.0"
  }
}

TSConfig

Some migrations require a tsconfig.json. You can add it as follows (do it only if stated in the migration description):

  • Add a devDependency to @eclipse-scout/tsconfig.
  • Run pnpm install to install the new dependency.
  • Create a tsconfig.json beside your package.json according to the Readme.md of the @eclipse-scout/tsconfig module.
{
  "devDependencies": {
    "@eclipse-scout/tsconfig": "~24.2.0"
  }
}

Module Map

The module map is used by certain migration tasks to automatically add imports. If a migration task requires a module map, do the following:

  • Adjust the moduleMap argument by replacing yourNamespace with the namespace in your index.js file. The moduleMap entry is used to add imports to your index.js automatically. If you omit it, you need to add the imports manually.
  • If you have dependencies to other Scout based modules, you add them to the moduleMap to have the imports to these modules created automatically. Add the namespace of the other module and the name of the npm package as follows: --moduleMap.otherNamespace @other/npm-module

ObjectType and MenuType Migration

In order to migrate string literals to class references and menu type constants, do the following:

  • Add a script in your package.json as described below.
  • Adjust the module map as described in the chapter Module Map
  • Run the migrate script by pressing the play button next to it in IntelliJ or using the command line: npm run migrate
  • Review the changes and add the missing imports, if there are any.
{
  "scripts": {
    "migrate": "scout-migrate --migrate objectType menuTypes --sources src/main/js/**/*.js --moduleMap.yourNamespace path:src/main/js/index.js"
  }
}

Widget and Column Map Migration

In order to create widget and column maps, do the following:

  • Create a tsconfig.json as described here
  • Add a rename and a migrate script in your package.json as described below.
  • Run the rename script by pressing the play button next to it in IntelliJ or using the command line: npm run rename. Commit the changes to ensure Git can track the renames correctly.
  • Run the migrate script.
  • Review and commit the changes.
{
  "scripts": {
    "rename": "scout-migrate --rename --sources src/main/js/**/*Model.js",
    "migrate": "scout-migrate --migrate widgetColumnMap --sources src/main/js/**/*Model.ts"
  }
}

Migrate to TypeScript

If you plan to migrate your Scout JS code base to TypeScript, use the migration tool for the initial migration. From there, you need to add the missing types, fix errors and clean up your code.

Important: if you have dependencies to other Scout based modules, make sure these modules are migrated to TypeScript first. We don't recommend migrating to TypeScript unless all dependencies are migrated.

The automatic migration includes:

  • Renaming the files to *.ts.
  • Declaring class properties
  • Declaring method parameters and return types based on JsDoc and naming conventions
  • Removing types from JsDoc
  • Adding imports for the types based on module maps
  • Adding method accessors

In order to run the TypeScript migration, do the following:

  • Ensure you have a clean Git working tree (no uncommitted files).
  • Create a tsconfig.json as described here
  • Add scripts in your package.json as described below.
  • Add an override in your package.json to fix the TypeScript version to 5.3.2 (the migrate tool will skip some migrations and print a warning about the wrong version otherwise). This is only needed for the migration and has to be removed afterwards.
  • Adjust the module map as described in the chapter Module Map
  • Add custom type maps if you have a large code base and would like to automate a little more, see Type Map
  • Run the rename script by pressing the play button next to it in IntelliJ or using the command line: npm run rename.
    • Adjust the paths in package.json (to index.ts), in webpack.config.js (to your entry point file) and in karma.conf.js (to test-index.ts).
    • Open index.ts and replace import * as self from './index.js'; with import * as self from './index';
    • Commit the changes to ensure Git can track the renames correctly.
  • Run the migrate script.
  • Review every file:
    • Verify / add the types of the class properties.
    • Verify / add the types of the method parameters and return values.
  • If you have custom widgets, you should create a Model and an EventMap for each widget. Please use existing widgets as template, e.g. Menu.ts, MenuModel.ts, MenuEventMap.ts.
    • The model needs to be extracted manually. Copy the relevant class properties to a separate model file. In your widget, implement the model interface and declare a model variable.
    • To create the event maps, you can run the event-maps script from below and copy the result into a separate event maps file.
  • If you use third party libraries, you may want to check if they provide types and add them to the devDependencies of your package.json (e.g. @types/jquery). See also Project Setup for TypeScript
  • Remove the added scripts, overrides and dependency to @eclipse-scout/migrate.
{
  "scripts": {
    "rename": "scout-migrate --rename --sources src/main/js/**/*.js",
    "migrate": "scout-migrate --rename false --migrate ts --sources src/main/js/**/*.ts --moduleMap.yourNamespace path:src/main/js/index.ts",
    "event-maps": "scout-migrate --print-event-maps --sources src/main/js/**/*.ts"
  },
  "pnpm": {
    "overrides": {
      "typescript": "5.3.2"
    }
  }
}

Type Map

Type maps are used to add types automatically based on naming rules. Scout provides many rules out of the box that should detect many types. If you have a large code base with custom types, you can add custom type maps.

To do so, create a config file ending with .mjs, e.g. migrate-config.mjs and configure your type maps like in the following example:

// The key has no special meaning
// The `name` is the name of the member variable or method parameter.
// If the predicate returns true, the type is used.
// The namespace in the type is used to create the import. To make it work, the module map has to contain an entry for that namespace.
// Example: doSomething(opts) -> doSomething(opts: Options)
const typeMap = {
  Options: {
    predicate: name => name === 'opts',
    type: 'yourNamespace.Options'
  }
};

// Compared to the typeMap above, the returnTypeMap is only used to determine the return types of functions.
// The 'name' parameter is the method name
// Example: createOptions() -> createOptions(): Options
const returnTypeMap = {
  Options: {
    predicate: name => name === 'createOptions',
    type: 'yourNamespace.Options'
  }
};

// Necessary if the imports should be created automatically.
const moduleMap = {
  yourNamespace: '@your-module/core'
};

// The default type that will be used if the parameter has no type.
// Can for example be set to 'any' after the migration to check whether all parameters have been typed.
let defaultParamType;

// The default type that will be used if the function has no return type.
// Can for example be set to 'void' after the migration to check whether all parameters have been typed.
let defaultReturnType;

export {typeMap, returnTypeMap, moduleMap, defaultParamType, defaultReturnType};

You can add as many mappings as you like, or none at all, they are completely optional. To activate your config, you need to pass the config object to the migrate script by using the --config option. For the TypeScript migration, you can do it as follows:

{
  "scripts": {
    "migrate": "scout-migrate --rename false --migrate ts --sources src/main/js/**/*.ts --config migrate-config.mjs"
  }
}

Note: you can either define the module map in the config file or pass it ass arguments to the script. If you do both, they will be merged. If they contain the same keys, the value passed via argument wins.