refactor: move declarations to ambient modules

README.md

@@ -26,10 +26,24 @@ A developers goodie for [Strapi Headless CMS](https://github.com/strapi/strapi)
 yarn add -D strapi-typed@latest
 ```
 
-and then use
+After install typings should be automatically available if you import from `@strapi/strapi`.
+
+If you want to use are internal utility types then use
+
+```typescript
+import { StringMap, OnlyStrings } from "@strapi/typed";
+```
+
+In few place plugin creator or Strapi consumer can extend couple of interfaces to add custom typings
+
+For example
 
 ```typescript
-import { IStrapi } from 'strapi-typed';
+declare module '@strapi/strapi' {
+  export interface IStrapiRequestQueryFiltersExtra {
+    threadOf?: number | string | null;
+  }
+}
 ```
 
 Enjoy 🎉

types/api.ts

@@ -1,93 +1,150 @@
-import { StringMap, Primitive, TypeResult } from "./common";
-import { PopulateClause, StrapiUser } from "./core";
-import { OnlyStrings } from "./utils";
-
-type SendStrapiContextFunction = (...args: unknown[]) => void;
-
-type ThrowStrapiContextFunction = (...args: unknown[]) => void;
-
-type StrapiHTTPErrorConstructor<T = StringMap<unknown>> = (message?: string, details?: T) => any
-
-export type StrapiRequestContext<
-  TBody extends {} = StringMap<string | number>,
-  TQuery extends {} = StringMap<string | number>,
-  TParams extends {} = StringMap<string | number>
-> = {
-  request: StrapiRequest<TBody>;
-  query: TQuery;
-  params: TParams;
-  pagination: StrapiPagination;
-  sort: StringMap<string | number>;
-  state: StrapiRequestContextState;
-
-  send: SendStrapiContextFunction;
-  throw: ThrowStrapiContextFunction;
-
-  // @see {https://github.com/jshttp/http-errors#list-of-all-constructors}
-  notFound: StrapiHTTPErrorConstructor;
-  badRequest: StrapiHTTPErrorConstructor;
-  unauthorized: StrapiHTTPErrorConstructor;
-  methodNotAllowed: StrapiHTTPErrorConstructor;
-  internalServerError: StrapiHTTPErrorConstructor;
-  notImplemented: StrapiHTTPErrorConstructor;
-};
-
-export type StrapiRequest<TBody extends {}> = {
-  body?: TBody;
-};
-
-export type StrapiRequestContextState = {
-    user?: StrapiUser
-};
-
-export type StrapiRequestQuery<T, TFields = keyof T> = {
-  filters?: {
-    threadOf?: number | string | null;
-    [key: string]: any;
-  } & {};
-  populate?: StrapiRequestQueryPopulateClause<OnlyStrings<TFields>>;
-  sort?: StringMap<any>;
-  fields?: StrapiRequestQueryFieldsClause<OnlyStrings<TFields>>;
-  pagination?: StrapiPagination;
-}
-
-export type StrapiRequestQueryFieldsClause<TKeys extends string = string> = Array<TKeys> | '*';
-
-export type StrapiRequestQueryPopulateClause<TKeys extends string = string> = PopulateClause<TKeys>;
-
-export type StrapiPagination = {
-  page?: number;
-  pageSize?: number;
-  start?: number;
-  limit?: number;
-  withCount?: boolean | string;
-};
-
-export type StrapiResponseMetaPagination = TypeResult<
-  Pick<StrapiPagination, "page" | "pageSize" | "start" | "limit"> & {
-    pageCount?: number;
-    total?: number;
+import { StringMap, OnlyStrings, TypeResult, Primitive } from "@strapi/typed";
+
+declare module "@strapi/strapi" {
+  type SendStrapiContextFunction = (...args: unknown[]) => void;
+
+  type ThrowStrapiContextFunction = (...args: unknown[]) => void;
+
+  type StrapiHTTPErrorConstructor<T = StringMap<unknown>> = (
+    message?: string,
+    details?: T
+  ) => any;
+
+  export type StrapiRequestContext<
+    TBody extends {} = StringMap<string | number>,
+    TQuery extends {} = StringMap<string | number>,
+    TParams extends {} = StringMap<string | number>
+  > = {
+    request: StrapiRequest<TBody>;
+    query: TQuery;
+    params: TParams;
+    pagination: StrapiPagination;
+    sort: StringMap<string | number>;
+    state: StrapiRequestContextState;
+
+    send: SendStrapiContextFunction;
+    throw: ThrowStrapiContextFunction;
+
+    // @see {https://github.com/jshttp/http-errors#list-of-all-constructors}
+    notFound: StrapiHTTPErrorConstructor;
+    badRequest: StrapiHTTPErrorConstructor;
+    unauthorized: StrapiHTTPErrorConstructor;
+    methodNotAllowed: StrapiHTTPErrorConstructor;
+    internalServerError: StrapiHTTPErrorConstructor;
+    notImplemented: StrapiHTTPErrorConstructor;
+  };
+
+  export type StrapiRequest<TBody extends {}> = {
+    body?: TBody;
+  };
+
+  export type StrapiRequestContextState = {
+    user?: StrapiUser;
+  };
+
+  export type StrapiRequestQuery<T, TFields = keyof T> = {
+    filters?: {
+      threadOf?: number | string | null;
+      [key: string]: any;
+    } & {};
+    populate?: StrapiRequestQueryPopulateClause<OnlyStrings<TFields>>;
+    sort?: StringMap<any>;
+    fields?: StrapiRequestQueryFieldsClause<OnlyStrings<TFields>>;
+    pagination?: StrapiPagination;
+  };
+
+  export type StrapiRequestQueryFieldsClause<TKeys extends string = string> =
+    | Array<TKeys>
+    | "*";
+
+  export type StrapiRequestQueryPopulateClause<TKeys extends string = string> =
+    PopulateClause<TKeys>;
+  interface ISendStrapiContextFunction {
+    (...args: unknown[]): void;
   }
->;
-
-export type StrapiResponseMeta = {
-  pagination: StrapiResponseMetaPagination;
-};
 
-export type StrapiPaginatedResponse<T> = {
-  data: Array<T>;
-  meta?: StrapiResponseMeta;
-};
+  interface IThrowStrapiContextFunction {
+    (...args: unknown[]): void;
+  }
 
-export type StrapiQueryParams = StringMap<string>;
+  export interface IStrapiRequestContext<
+    TBody extends {} = StringMap<string | number>,
+    TQuery extends {} = StringMap<string | number>,
+    TParams extends {} = StringMap<string | number>
+  > {
+    request: StrapiRequest<TBody>;
+    query: TQuery;
+    params: TParams;
+    pagination: StrapiPagination;
+    sort: StringMap<string | number>;
+    state: StrapiRequestContextState;
+
+    send: ISendStrapiContextFunction;
+    throw: IThrowStrapiContextFunction;
+  }
 
-export type StrapiQueryParamsParsed = StringMap<Primitive>;
+  export interface IStrapiController<
+    TBody extends {} = StringMap<string | number>,
+    TQuery extends {} = StringMap<string | number>,
+    TParams extends {} = StringMap<string | number>,
+    TResult = unknown
+  > {
+    (ctx: IStrapiRequestContext<TBody, TQuery, TParams>): TResult;
+  }
 
-export type StrapiQueryParamsParsedOrderBy = string | Array<string>;
+  export interface IStrapiRequestQueryFiltersExtra {}
 
-type StrapiQueryParamsParsedFilterValue<TKeys extends string = string> =
-  | Primitive
-  | Partial<Record<TKeys, unknown>>;
+  export interface IStrapiRequestQuery<T, TFields = keyof T> {
+    filters?: {
+      [key: string]: any;
+    } & IStrapiRequestQueryFiltersExtra;
+    populate?: StrapiRequestQueryPopulateClause<OnlyStrings<TFields>>;
+    sort?: StringMap<any>;
+    fields?: StrapiRequestQueryFieldsClause<OnlyStrings<TFields>>;
+    pagination?: StrapiPagination;
+  }
 
-export type StrapiQueryParamsParsedFilters<TValue, TKeys = keyof TValue> = 
-Partial<Record<OnlyStrings<TKeys>, StrapiQueryParamsParsedFilterValue<OnlyStrings<TKeys>>>>;
+  export type StrapiPagination = {
+    page?: number;
+    pageSize?: number;
+    start?: number;
+    limit?: number;
+    withCount?: boolean | string;
+  };
+
+  export type StrapiResponseMetaPagination = TypeResult<
+    Pick<StrapiPagination, "page" | "pageSize" | "start" | "limit"> & {
+      pageCount?: number;
+      total?: number;
+    }
+  >;
+
+  export type StrapiResponseMeta = {
+    pagination: StrapiResponseMetaPagination;
+  };
+
+  export type StrapiPaginatedResponse<T> = {
+    data: Array<T>;
+    meta?: StrapiResponseMeta;
+  };
+
+  export type StrapiQueryParams = StringMap<string>;
+
+  export type StrapiQueryParamsParsed = StringMap<Primitive>;
+
+  export type StrapiQueryParamsParsedOrderBy = string | Array<string>;
+
+  type StrapiQueryParamsParsedFilterValue<TKeys extends string = string> =
+    | Primitive
+    | Partial<Record<TKeys, unknown>>;
+
+  export type StrapiQueryParamsParsedFilters<
+    TValue,
+    TKeys = keyof TValue
+  > = Partial<
+    Record<
+      OnlyStrings<TKeys>,
+      StrapiQueryParamsParsedFilterValue<OnlyStrings<TKeys>>
+    >
+  >;
+}

types/common.d.ts

@@ -1,15 +1,17 @@
-export type PropType<TObj, TProp extends keyof TObj> = TObj[TProp];
+declare module "@strapi/typed" {
+  export type PropType<TObj, TProp extends keyof TObj> = TObj[TProp];
 
-export type Primitive = string | number | object | boolean | null | undefined;
+  export type Primitive = string | number | object | boolean | null | undefined;
 
-export type KeyValueSet<T> = Record<string, T | any>;
+  export type KeyValueSet<T> = Record<string, T | any>;
 
-export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
 
-export type StringMap<Type> = Record<string, Type>;
+  export type StringMap<Type> = Record<string, Type>;
 
-export type TypeResult<T> = {
-  [K in keyof T]: T[K];
-};
+  export type TypeResult<T> = {
+    [K in keyof T]: T[K];
+  };
 
-export type Id = number | string;
+  export type Id = number | string;
+}