[Request]: Typescript typings

Maraket commented 1 month ago

Summary

Provide examples of typescript typings in method prototypes, not just how to import elements rather than using require.

Why is it needed?

When trying to maintain code that is expected to have strict typing, this becomes difficult without an easy reference for what types to use for what calls. Additionally, this can simplify coding as it allows IDEs to then do auto-completion and catch bugs earlier in the development process.

Suggested solution(s)

Update current examples showing how to write the code with the appropriate types defined. Some examples of what I would expect to see include:

From https://docs.strapi.io/dev-docs/backend-customization/routes#public-routes, for instances where you are defining a default export (the type in my example I made up as I don't know the appropriate type)
```
import { RouteDefinition } from '@strapi/strapi`;
```

export default { routes: [ { method: 'GET', path: '/articles/customRoute', handler: 'api::api-name.controllerName.functionName', // or 'plugin::plugin-name.controllerName.functionName' for a plugin-specific controller config: { auth: false, }, }, ], } satisfies RouteDefinition;

- From https://docs.strapi.io/dev-docs/backend-customization/controllers, where you are defining methods, then ensure to include the types (again unsure of what `ctx` should be, and all I can confirm is it is not `RequestContext`):
```ts
import { Strapi, factories, ControllerRequestContext } from "@strapi/strapi";

export default factories.createCoreController(
  "api::restaurant.restaurant",
  ({ strapi }: { Strapi }) => ({
    async find(ctx: ControllerRequestContext) {
      const sanitizedQueryParams = await this.sanitizeQuery(ctx);
      const { results, pagination } = await strapi
        .service("api::restaurant.restaurant")
        .find(sanitizedQueryParams);
      const sanitizedResults = await this.sanitizeOutput(results, ctx);

      return this.transformResponse(sanitizedResults, { pagination });
    },
  })
);

Related issue(s)/PR(s)

No response

pwizla commented 1 month ago

Thanks for the suggestion. I'll check with Strapi core engineers and see what we can do.

Convly commented 4 weeks ago

Hey,

for instances where you are defining a default export (the type in my example I made up as I don't know the appropriate type)

import { RouteDefinition } from '@strapi/strapi`;

export default  {
  routes: [
    {
      method: 'GET',
      path: '/articles/customRoute',
      handler: 'api::api-name.controllerName.functionName', // or 'plugin::plugin-name.controllerName.functionName' for a plugin-specific controller
      config: {
        auth: false,
      },
    },
  ],
} satisfies RouteDefinition;

That could be a good idea. Another one we have is potentially export typed factories to eliminate the need for manual typings + be able to propose the same benefits for both JS and TS projects

where you are defining methods, then ensure to include the types (again unsure of what ctx should be, and all I can confirm is it is not RequestContext):

import { Strapi, factories, ControllerRequestContext } from "@strapi/strapi";

export default factories.createCoreController(
  "api::restaurant.restaurant",
  ({ strapi }: { Strapi }) => ({
    async find(ctx: ControllerRequestContext) {
      const sanitizedQueryParams = await this.sanitizeQuery(ctx);
      const { results, pagination } = await strapi
        .service("api::restaurant.restaurant")
        .find(sanitizedQueryParams);
      const sanitizedResults = await this.sanitizeOutput(results, ctx);

      return this.transformResponse(sanitizedResults, { pagination });
    },
  })
);

This one is surprising, createCoreController should already infer the correct types for the methods. You shouldn't need to manual add the context type :thinking:

strapi / documentation