Merge pull request #11 from apilytics/documentation

Thoroughly document all exported symbols with JSDoc

Author: ruohola

packages/core/src/index.ts

@@ -6,28 +6,64 @@ interface Params {
   apiKey: string;
   path: string;
   method: string;
-  statusCode: number | null;
   timeMillis: number;
   query?: string;
+  statusCode?: number | null;
   apilyticsIntegration?: string;
   integratedLibrary?: string;
 }
 
+/**
+ * Send API analytics data to Apilytics (https://apilytics.io).
+ * Does the sending as fire-and-forget background task.
+ *
+ * @param params
+ * @param params.apiKey - The API key for your Apilytics origin.
+ * @param params.path - Path of the user's HTTP request, e.g. '/foo/bar/123'.
+ * @param params.method - Method of the user's HTTP request, e.g. 'GET'.
+ * @param params.timeMillis - The amount of time in milliseconds it took
+ *     to respond to the user's request.
+ * @param params.query - Optional query string of the user's HTTP request
+ *     e.g. 'key=val&other=123'. An empty string and null are treated equally.
+ *     Can have an optional '?' at the start.
+ * @param params.statusCode - Status code for the sent HTTP response.
+ *     Can be omitted (or null) if the middleware could not get the status code
+ *     for the response. E.g. if the inner request handling threw an exception.
+ * @param params.apilyticsIntegration - Name of the Apilytics integration that's
+ *     calling this, e.g. 'apilytics-node-express'.
+ *     No need to pass this when calling from user code.
+ * @param params.integratedLibrary - Name and version of the integration that
+ *     this is used in, e.g. 'express/4.17.2'.
+ *     No need to pass this when calling from user code.
+ *
+ * @example
+ *
+ *    const timer = milliSecondTimer();
+ *    const res = await handler(req);
+ *    sendApilyticsMetrics({
+ *      apikey: "<your-api-key>",
+ *      path: req.path,
+ *      query: req.queryString,
+ *      method: req.method,
+ *      statusCode: res.statusCode,
+ *      timeMillis: timer(),
+ *    });
+ */
 export const sendApilyticsMetrics = ({
   apiKey,
   path,
-  query,
   method,
-  statusCode,
   timeMillis,
+  query,
+  statusCode,
   apilyticsIntegration,
   integratedLibrary,
 }: Params): void => {
   const data = JSON.stringify({
     path,
     query: query || undefined,
     method,
-    statusCode,
+    statusCode: statusCode ?? undefined,
     timeMillis,
   });
   let apilyticsVersion = `${
@@ -65,6 +101,13 @@ export const sendApilyticsMetrics = ({
   });
 };
 
+/**
+ * Times the amount of milliseconds something takes to execute.
+ * The timer starts when this is initially called.
+ *
+ * @returns A function that can be called to stop the timer.
+ *     That function's return value is the elapsed time.
+ */
 export const milliSecondTimer = (): (() => number) => {
   const startTimeNs = process.hrtime.bigint();
 

packages/express/src/index.ts

@@ -5,6 +5,21 @@ import type { NextFunction, Request, RequestHandler, Response } from 'express';
 
 const EXPRESS_VERSION = require('express/package.json').version;
 
+/**
+ * Express middleware that sends API analytics data to Apilytics (https://apilytics.io).
+ *
+ * @param apiKey - The API key for your Apilytics origin.
+ * @returns An Express middleware that can be passed to `app.use()`.
+ *
+ * @example
+ *
+ *     const { apilyticsMiddleware } = require('@apilytics/express');
+ *     const express = require('express');
+ *
+ *     const app = express();
+ *
+ *     app.use(apilyticsMiddleware("your-api-key"));
+ */
 export const apilyticsMiddleware = (
   apiKey: string | undefined,
 ): RequestHandler => {

packages/next/__tests__/index.test.ts

@@ -174,7 +174,6 @@ describe('withApilytics()', () => {
     expect(data).toStrictEqual({
       path: '/error',
       method: 'GET',
-      statusCode: null,
       timeMillis: expect.any(Number),
     });
   });

packages/next/src/index.ts

@@ -5,6 +5,23 @@ import type { NextApiHandler, NextApiRequest, NextApiResponse } from 'next';
 
 const NEXT_VERSION = require('next/package.json').version;
 
+/**
+ * Next.js middleware that sends API analytics data to Apilytics (https://apilytics.io).
+ *
+ * @param handler - Next.js API route handler that this middleware should apply to.
+ * @param apiKey - The API key for your Apilytics origin.
+ * @returns A new API route handler which wraps the one that was passed in.
+ *
+ * @example
+ *
+ *    import { withApilytics } from '@apilytics/next';
+ *
+ *    const handler = async (req, res) => {
+ *      // ...
+ *    };
+ *
+ *    export default withApilytics(handler, "<your-api-key>");
+ */
 export const withApilytics = <T>(
   handler: NextApiHandler<T>,
   apiKey: string | undefined,

tsconfig.json

@@ -7,7 +7,7 @@
     "strict": true,
     "declaration": true,
     "sourceMap": true,
-    "removeComments": true,
+    "inlineSources": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
     "allowSyntheticDefaultImports": true,