OData Typify Middleware

Typify is a middleware for the UI5 Server Module of the UI5 Command Line Interface. It is used to automatically generate TypeScript types for your OData endpoints and can be usefull in any UI5 TypeScript project that is based on OData.

The type generation is done while your ui5 serve is running. Whenever your app is loading an OData $metadata file from your endpoint, the middleware is intercepting it and creates a .ts TypeScript type file.

Files are created for all of your OData endpoints. If your Endpoint has changed, the file will be updated on the fly.

There is also an option to create types on demand.

Installation

npm install --save-dev @elevatory/odata-typify-middleware

Typify is only used to leverage the development process. So you should install it as a dev dependency with the --save-dev flag.

ui5.yaml

Add the middleware to your ui5.yaml in the server section as a customMiddleware.

Example:

server:
  customMiddleware:
    - name: "@elevatory/odata-typify-middleware"
      beforeMiddleware: compression

HINT: The middleware needs to run before middleware compression.

package.json

Remember to also include it in your package.json in the ui5 dependencies section.

    "ui5": {
        "dependencies": [
            "@elevatory/odata-typify-middleware"
        ]
    }

Usage

Typify can be used as a middleware and therefore run all the time within your ui5 serve. This is the preferred way to work with it. Another option is to run the module on demand.

Run as middleware

Start your application with ui5 serve.
As soon as the tooling fetches the metadata document from the server, Typify will parse your metadata and create type files. If this does not happen, do a force refresh (e.g. CTRL + F5) in your browser as the metadata call might be cached by your browser and not triggering the middleware.

Run on demand

Run the command npx odata-typify to create types on demand.
You need to enter the username and password or add UI5_USERNAME and UI5_PASSWORDas environment variables.
Typify will create types based on the OData configuration from the projects manifest.json and url in ui5.yaml for ui5-middleware-route-proxy.

What Typify does on success

After successfully executing Typify the types will be created in the project root in a folder (see configuration). The naming will be servicename.metadata.ts, where servicename gets replaces with the name of your OData service.

Additional Configuration

Target Directory for Metadata files

You can configure in which path Typify will create your type files. Therefore you can use the optional target property in the configuration section of the middleware in your ui5.yaml.

    - name: "@elevatory/odata-typify-middleware"
      beforeMiddleware: compression
      configuration:
        target: src/some-great-directory/    

Please make sure that the user running ui5-server has write authorization for the directory.

If target directory does not exist, it will be created. The target needs to be under the current working directory/project root. If no target is given, the default src/metadata/ will be used.

HINT: Do not forget the trailing slashes for the directory!

File Naming for Metadata File

You can configure the name of the type file.
You can use the option mapping property in the configuration section of the middleware in your ui5.yaml.

The mapping property will take a list of mappings in the following format:
datasource-name: desired_filename.ts

If no mapping is given, the name will be servicename.metadata.ts.

The file will be created under src/metadata by default, if not configured by optional target property.

This would be an example manifest.json Datasource configuration:

{
    ...
    "sap.app": {
        ...
        "dataSources": {
            "GWSAMPLE_BASIC": {
                "uri": "/sap/opu/odata/IWBEP/GWSAMPLE_BASIC/",
                "type": "OData"
            }
        }
    }
}            

This would be the middleware configuration to create a types.ts for the datasource GWSAMPLE_BASIC

    - name: "@elevatory/odata-typify-middleware"
      beforeMiddleware: compression
      configuration:
        mapping:
          GWSAMPLE_BASIC: types.ts

Set Log detail level to debug

The middleware log error messages if errors occur.
If you wish to receive more information about the middleware processing you can enhance the log level by adding a debug flag.
This is to be set in the configuration part of the middleware configuration in your ui5.yaml.

    - name: "@elevatory/odata-typify-middleware"
      beforeMiddleware: compression
      configuration:
        debug: true

Avoiding Reload Loops

You have to take care, if you have a filesystem watcher, that is monitoring your project source code directory and doing transpiling on the fly and an additional tool for live reloading your application base on changed files.

This will be the case if you for example use tsc or babel with the --watch flag and an additional live reload middleware. You will experience an infinity reload loop, triggerd by Typify that creates type files, that cause a reaload which again triggers Typify to create type files and so on.

To avoid this, add the type files to the ignore section of your transpiler. This is in any way a good choice because type files are not needed in your transpiled code. If you use babel, you can just add *.metadata.ts to your .babelrc.json ignore section.

    "ignore": [
        "**/*.d.ts",
        "**/*.metadata.ts"       
    ]

Authors

The development is carried out by Elevatory. We specialize in the development of SAP applications with ABAP, SAPUI5/Fiori and SAP HANA.