fix: type definations (#51)

index.d.ts

@@ -1,33 +1,103 @@
-import { ParsedUrlQuery } from 'querystring';
-interface RequestResponse {
-  req: any;
-  res: {
-    send: any
-  };
-}
-export interface SendParams extends RequestResponse {
-  data: string;
-}
+import { IncomingMessage, ServerResponse } from "http";
 
-declare function CacheableResponse(params: CacheableResponse.InputParams): CacheableResponse.ReturnResponse;
 /**
- * Cacheable response  is a HTTP middleware for serving a pre-calculated response.
+ * Cacheable response is a HTTP middleware for serving a pre-calculated response.
  */
+
+declare function CacheableResponse<
+  Options extends CacheableResponse.GetOpts = CacheableResponse.GetOpts,
+  Props extends CacheableResponse.Props = {},
+  Data extends {} = {}
+>(
+  params: CacheableResponse.InputParams<Options, Props, Data>
+): (opts: Options) => any;
+
+/** Framework agnostic req and res object */
+export interface HttpContext {
+  req: IncomingMessage;
+  res: ServerResponse;
+}
+
 declare namespace CacheableResponse {
-  export interface InputParams {
-    get: (params: any) => Promise<{ data, ttl?: number }>;
-    send: (params: SendParams, ...props) => void
-    ttl?: number; // milliseconds
+  export interface InputParams<
+    Options extends GetOpts,
+    GetReturnProps extends Props,
+    Data extends {}
+  > {
+    /**
+     * The method to be called for creating a fresh cacheable response associated with the current route path.
+     */
+    get: (
+      opts: Options
+    ) => Promise<
+      (Optional<Cache<Data>, "etag" | "ttl" | "createdAt"> & GetReturnProps) | null
+    >;
+
+    /**
+     * The method used to determinate how the content should be rendered.
+     */
+    send: (
+      opts: GetReturnProps & { data: Data } & Pick<Options, "req" | "res">
+    ) => any;
+
+    /** Cache provider, default to 'keyv' */
+    cache?: CacheProvider<GetReturnProps, Data>;
+
+    /** Enable compress, default false */
     compress?: boolean;
-    serialize?: (obj: object) => string;
-    deserialize?: (str: string) => object;
-    cache?: boolean;
-    getKey: (req: any) => string,
-    revalidate?: (ttl: number) => number;
+
+    /** Get cache key from request context */
+    getKey?: (opts: Options) => string;
+
+    /**
+     * Number of milliseconds that indicates grace period after response cache expiration for refreshing it in the background.
+     *  The latency of the refresh is hidden from the user.
+     * You can provide a function, it will receive ttl as first parameter or a fixed value.
+     *  The value will be associated with stale-while-revalidate directive.
+     */
+    revalidate?: (ttl: number) => number | number;
+
+    /** ttl default to 7200000 */
+    ttl?: number;
+
+    /** Compress opts pass through to compress-brotli */
+    serialize?: (o: any) => string;
+
+    deserialize?: (o: string) => any;
+  }
+
+  export type GetOpts = HttpContext & Props;
+
+  export interface CacheProvider<P extends Props, V = any> {
+    /** Returns the cached value, or the compressed buffer when compress option is set to true. */
+    get(key: string): Promise<Buffer | (Cache<V> & P) | undefined>;
+
+    /**
+     * Set a value. You can implements an expiry TTL in milliseconds.
+     */
+    set(
+      key: string,
+      value: Buffer | (Cache<V> & P),
+      ttl: number
+    ): Promise<true>;
+  }
+
+  interface Props {
+    [key: string]: any;
+  }
+
+  interface Cache<T> {
+    etag: string;
+    /** JS timestamps */
+    createdAt: number;
+    /** ttl in milliseconds */
+    ttl: number;
+    /** cached value */
+    data: T;
   }
-  type ReturnFunction = (params: SendParams) => void
-  export type ReturnResponse = (params: any) => ReturnFunction
 
+  type Optional<T extends object, K extends keyof T = keyof T> = Omit<T, K> &
+    Partial<Pick<T, K>>;
 }
 
 export default CacheableResponse;