Use interface for cds_services to allow module augmentation

[aschmidt93]

cds.services is currently typed as type cds_services: export type cds_services = { [name: string]: Service }. Types can not be extended via module augmentation, thus this does not work:

// index.d.ts
import "@sap/cds";

declare module "@sap/cds" {
  export declare type cds_services = { foo: "bar" };
}

cds.services would still be typed as { [name: string]: Service }.

In order for module augmentation to work, cds_services has to be an interface.

Idea

declare module "@sap/cds" {
  type service_dict = { [name: string]: Service }
  export interface cds_services extends service_dict {}
}

Now module augmentation can be used to extend cds_services:

// index.d.ts
import "@sap/cds";

declare module "@sap/cds" {
  export interface cds_services {
    foo: "bar";
  }
}

Now, cds.services.foo is properly typed as "bar".

Reason

This can be used to narrow down the type of cds_services to only those services that actually exist in the project. Additionally, cds-typer can be used to type those services.

[daogrady]

Hi Andreas,

thank you for your suggestion. I am actually not sure if module augmentation is the right approach here, as that is kind of a "last resort" technique and here it is used for added convenience. Wouldn't a helper type appropriately address the underlying issue?

Best,
Daniel

[aschmidt93]

Hi Daniel,

sorry for the late response. I do think module augmentation is the right approach here unless there's a way for cds-types to automatically pick up the services generated by cds-typer and type cds_services accordingly.

The alternative would be to manually type each time a service is accessed:

// `OrderServiceTypes` is the file generated by cds-typer (import type * as OrderServiceTypes from "...")
// TypedService is a custom type that uses the output of cds-typer to type the generic methods of a service, e.g. `send` or `emit`
const orderService : TypedService<typeof OrderServiceTypes> = cds.services["OrderService"];

// compile time checked with `TypedService`
await orderService.emit("foo", {bar : 0});

I think this is cumbersome and prone to error, especially in a larger code base with many service-to-service interactions. Therefore, module augmentation fits perfectly. It allows users to define once in a central place which services are available and additionally users can type those services, if they choose to. Additionally, it requires no runtime code. And the change required in cds-types is miniscule, isn't it?

[daogrady]

Hi Andreas,

sorry for the late response as well. 🙂
I have no strong sentiment towards using type or interface here. But as this is a rather fundamental change, I'd like to give it a more thorough look. I'll have to postpone it until mid November, as I will be ooo for the next two weeks. Just giving a headsup.

Best,
Daniel