[k6] Add type documentation (DefinitelyTyped#37056)

* k6: Document fail * k6: Remove docs link Complete docs are included in the doc comment. * k6: Document group * k6: Document sleep * k6: Order signature docs before remarks Renders more usefully in Visual Studio Code. * k6: Document check * k6: Space documented declarations * k6: Space section headers * k6: Document method releases * k6: Simplify check documentation * k6: Simplify fail documentation * k6: Simplify group documentation * k6: Document package * k6: Compress documentation * k6: Document Checker * k6: Document Checkers * k6: Link to check docs * k6: Link to fail docs * k6: Link to group docs * k6: Link to sleep docs * k6: Correct returns tag * k6: Document check type param * k6: Document group return type * k6: Document byte * k6: Document bytes * k6: Document JSON types * k6: Configure API Extractor Enables validating docs with: mkdir -p etc; api-extractor run -c api-extractor.json -l * k6: Ignore docs build * k6: Document doc comment validation * k6: Disable API report generation * k6: Disable doc model generation * k6: Disable .d.ts rollup generation * k6: Disable TSDoc metadata generation * k6: Document typeParam tag warnings * k6/global: Document module * k6/global: Normalize section comments * k6/global: Document open * k6/global: Document __ENV * k6/global: Refine __ENV type * k6/global: Document __VU * k6/global: Document __ITER * k6/global: Document console * k6/global: Normalize VU logic references * k6: Improve section header visibility * k6/crypto: Document module * k6/crypto: Document randomBytes * k6/crypto: Document hmac * k6/crypto: Document md4 * k6/crypto: Document md5 * k6/crypto: Document sha1 * k6/crypto: Document sha256 * k6/crypto: Document sha384 * k6/crypto: Document sha512 * k6/crypto: Document sha512_224 * k6/crypto: Document sha512_256 * k6/crypto: Document ripemd160 * k6/crypto: Document createHash * k6/crypto: Document createHMAC * k6/crypto: Link to createHash docs * k6/crypto: Document Algorithm * k6/crypto: Document StringEncoding * k6/crypto: Document BinaryEncoding * k6/crypto: Document OutputEncoding * k6/crypto: Document Output * k6/crypto: Document Hasher * k6/crypto: Document Hasher#update * k6/crypto: Document Hasher#digest * k6/crypto: Update formatting Repo formatter really wants it this way. * k6/encoding: Document module * k6/encoding: Document b64encode * k6/encoding: Document b64decode * k6/encoding: Document Base64Variant * k6/html: Document module * k6/html: Document parseHTML * k6/html: Add section headers * k6/html: Document Selection * k6: Disable redundant JSDoc check Incorrectly applies to our TSDoc doc comments. * k6/global: Add missing semicolon * k6/global: Correct test * k6/html: Update tests * k6/html: Accept overloads for documentation The overloads in these cases produce more natural IntelliSense rendering of the documentation. * k6/html: Document FormValue * k6/html: Document Tester * k6/html: Document Handler * k6/html: Document Mapper * k6/html: Qualify FormValue description * k6/html: Normalize section header language * k6/html: Document Attribute * k6/html: Document NodeType * k6/html: Document Element * k6/html: Document AnchorElement * k6/html: Document AreaElement * k6/html: Link to Element docs * k6/html: Document AudioElement * k6/html: Document BaseElement * k6/html: Document ButtonElement * k6/html: Document CanvasElement * k6/html: Document DataElement * k6/html: Document DataListElement * k6/html: Document DelElement * k6/html: Document EmbedElement * k6/html: Document FieldSetElement * k6/html: Document FormElement * k6/html: Document FormFieldElement * k6/html: Document HrefElement * k6/html: Document IFrameElement * k6/html: Document ImageElement * k6/html: Document InputElement * k6/html: Document InsElement * k6/html: Document KeygenElement * k6/html: Document LabelElement * k6/html: Document LegendElement * k6/html: Document LiElement * k6/html: Document LinkElement * k6/html: Document MapElement * k6/html: Document MediaElement * k6/html: Document MetaElement * k6/html: Document MeterElement * k6/html: Document ModElement * k6/html: Document ObjectElement * k6/html: Document OListElement * k6/html: Document OptGroupElement * k6/html: Document OptionElement * k6/html: Document OutputElement * k6/html: Document ParamElement * k6/html: Document PreElement * k6/html: Document ProgressElement * k6/html: QuoteElement * k6/html: Document ScriptElement * k6/html: Document SelectElement * k6/html: Document SourceElement * k6/html: Document StyleElement * k6/html: Document TableBodyElement * k6/html: Document TableCellElement * k6/html: Document TableColElement * k6/html: Document TableDataCellElement * k6/html: Document TableElement * k6/html: Document TableFootElement * k6/html: Document TableHeadElement * k6/html: Document TableHeaderCellElement * k6/html: Document TableRowElement * k6/html: Document TableSectionElement * k6/html: Document TextAreaElement * k6/html: Document TimeElement * k6/html: Document TitleElement * k6/html: Document TrackElement * k6/html: Correct MediaElement#textTracks return type * k6/html: Document UListElement * k6/html: Document VideoElement * k6/html: Update HrefElement test * k6/http: Document module * k6/http: Add section headers * k6/http: Normalize refined params type name * k6/http: Normalize refined batch request type names * k6/http: Remove generics justification * k6/http: Document del * k6/http: Document get * k6/http: Document options * k6/http: Document patch * k6/http: Document post * k6/http: Document put * k6/http: Document request * k6/http: Document batch * k6/http: Document file * k6/http: Document cookieJar * k6/http: Include release tags * k6/http: Document Params * k6/http: Document RefinedParams * k6/http: Document AuthMethod * k6/http: Document ResponseType * k6/http: Document ParamsCookieValue * k6/http: Document RequestBody * k6/http: Document StructuredRequestBody * k6/http: Document batch request types * k6/http: Document refined batch request types * k6/http: Document BatchResponses * k6/http: Document Response properties * k6/http: Document Response.html * k6/http: Document Response.json * k6/http: Document Response.clickLink * k6/http: Document Response.submitForm * k6/http: Define SSL/TLS version constants * k6/http: Define OCSP status constants * k6/http: Document OCSP reason constants * k6/http: Define CipherSuite * k6/http: Document Protocol * k6/http: Document CipherSuite * k6/http: Document RefinedResponse * k6/http: Document ResponseBody * k6/http: Document RefinedResponseBody * k6/http: Document RequestCookie * k6/http: Document ResponseCookie * k6/http: Correct Unix time specifications * k6/http: Document FileData * k6/http: Accept formatter changes * k6/http: Link to FileData docs * k6/http: Accept formatter changes * k6/http: Document CookieJar * k6/http: Document CookieJarCookies * k6/http: CookieOptions * k6/metrics: Document module * k6/metrics: Document Metric * k6/metrics: Document Counter * k6/metrics: Document Gauge * k6/metrics: Document Rate * k6/metrics: Document Trend * k6/ws: Document module * k6/ws: Add section headers * k6/ws: Document connect * k6/ws: Document Params * k6/ws: Document Executor * k6/ws: Document Response * k6/ws: Document Socket * k6/ws: Document EventType * k6/ws: Document TimerHandler * k6/ws: Document event handlers * k6/ws: Document WebSocketError * k6/options: Document module * k6/options: Document Options * k6/options: Document CollectorOptions * k6/options: Document Stage * k6/options: Document threshold specifications * k6/options: Document Certificate * k6: Remove API Extractor config No obvious way to get the repo test to accept it. To be restored when an approach is discovered.
smor · Jul 23, 2019 · 518db03 · 518db03
1 parent b7c382e
commit 518db03
Show file tree

Hide file tree

Showing 12 changed files with 2,343 additions and 107 deletions.
diff --git a/types/k6/crypto.d.ts b/types/k6/crypto.d.ts
@@ -1,29 +1,175 @@
+/*
+ * Cryptography utilities.
+ * https://docs.k6.io/docs/k6crypto
+ */
+
 import { bytes } from '.';
 
+/**
+ * Generate random bytes.
+ * @param size - Number of bytes to generate.
+ * @returns Random bytes.
+ * @public
+ */
 export function randomBytes(size: number): bytes;
-export function hmac(algorithm: Algorithm, secret: string, data: string, outputEncoding: BinaryEncoding): bytes;
-export function hmac(algorithm: Algorithm, secret: string, data: string, outputEncoding: StringEncoding): string;
-export function md4(input: string, outputEncoding: BinaryEncoding): bytes;
-export function md4(input: string, outputEncoding: StringEncoding): string;
-export function md5(input: string, outputEncoding: BinaryEncoding): bytes;
-export function md5(input: string, outputEncoding: StringEncoding): string;
-export function sha1(input: string, outputEncoding: BinaryEncoding): bytes;
-export function sha1(input: string, outputEncoding: StringEncoding): string;
-export function sha256(input: string, outputEncoding: BinaryEncoding): bytes;
-export function sha256(input: string, outputEncoding: StringEncoding): string;
-export function sha384(input: string, outputEncoding: BinaryEncoding): bytes;
-export function sha384(input: string, outputEncoding: StringEncoding): string;
-export function sha512(input: string, outputEncoding: BinaryEncoding): bytes;
-export function sha512(input: string, outputEncoding: StringEncoding): string;
-export function sha512_224(input: string, outputEncoding: BinaryEncoding): bytes;
-export function sha512_224(input: string, outputEncoding: StringEncoding): string;
-export function sha512_256(input: string, outputEncoding: BinaryEncoding): bytes;
-export function sha512_256(input: string, outputEncoding: StringEncoding): string;
-export function ripemd160(input: string, outputEncoding: BinaryEncoding): bytes;
-export function ripemd160(input: string, outputEncoding: StringEncoding): string;
+
+/**
+ * Produce HMAC.
+ * https://docs.k6.io/docs/hmac-algorithm-secret-data-outputencoding
+ * @param algorithm - Hash algorithm.
+ * @param secret - Shared secret.
+ * @param data - Input data.
+ * @param outputEncoding - Output encoding.
+ * @returns Produced HMAC.
+ * @public
+ */
+export function hmac<OE extends OutputEncoding>(
+    algorithm: Algorithm,
+    secret: string,
+    data: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with MD4.
+ * https://docs.k6.io/docs/md4-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns MD4 digest.
+ * @public
+ */
+export function md4<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with MD5.
+ * https://docs.k6.io/docs/md5-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns MD5 digest.
+ * @public
+ */
+export function md5<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with SHA-1.
+ * https://docs.k6.io/docs/sha1-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns SHA-1 digest.
+ * @public
+ */
+export function sha1<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with SHA-256.
+ * https://docs.k6.io/docs/sha256-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns SHA-256 digest.
+ * @public
+ */
+export function sha256<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with SHA-384.
+ * https://docs.k6.io/docs/sha384-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns SHA-384 digest.
+ * @public
+ */
+export function sha384<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with SHA-512.
+ * https://docs.k6.io/docs/sha512-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns SHA-512 digest.
+ * @public
+ */
+export function sha512<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with SHA-512/224.
+ * https://docs.k6.io/docs/sha512_224-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns SHA-512/224 digest.
+ * @public
+ */
+export function sha512_224<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with SHA-512/256.
+ * https://docs.k6.io/docs/sha512_256-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns SHA-512/256 digest.
+ * @public
+ */
+export function sha512_256<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Hash with RIPEMD-160.
+ * https://docs.k6.io/docs/ripemd160-input-outputencoding
+ * @param input - Data to hash.
+ * @param outputEncoding - Output encoding.
+ * @returns RIPEMD-160 digest.
+ * @public
+ */
+export function ripemd160<OE extends OutputEncoding>(
+    input: string,
+    outputEncoding: OE
+): Output<OE>;
+
+/**
+ * Create a hashing object.
+ * https://docs.k6.io/docs/createhash-algorithm
+ * @param algorithm - Hash algorithm.
+ * @returns Hashing object.
+ * @public
+ */
 export function createHash(algorithm: Algorithm): Hasher;
+
+/**
+ * Create an HMAC hashing object.
+ * https://docs.k6.io/docs/createhmacalgorithm-secret
+ * @param algorithm - Hash algorithm.
+ * @param secret - Shared secret.
+ * @returns HMAC hashing object.
+ * @public
+ */
 export function createHMAC(algorithm: Algorithm, secret: string): Hasher;
 
+/**
+ * Hash algorithm.
+ * @public
+ */
 export type Algorithm =
     | 'md4'
     | 'md5'
@@ -34,12 +180,54 @@ export type Algorithm =
     | 'sha512_224'
     | 'sha512_256'
     | 'ripemd160';
+
+/**
+ * String output encoding.
+ * @public
+ */
 export type StringEncoding = 'hex' | 'base64' | 'base64url' | 'base64rawurl';
+
+/**
+ * Binary output encoding.
+ * @public
+ */
 export type BinaryEncoding = 'binary';
 
+/**
+ * Output encoding.
+ * @public
+ */
+export type OutputEncoding = StringEncoding | BinaryEncoding;
+
+/**
+ * Output type. Varies with output encoding.
+ * @typeParam OE - Output encoding.
+ * @public
+ */
+export type Output<OE extends OutputEncoding> = OE extends StringEncoding
+    ? string
+    : OE extends BinaryEncoding
+    ? bytes
+    : never;
+
+/**
+ * Hashing object.
+ * https://docs.k6.io/docs/hasher-k6crypto
+ * @public
+ */
 export abstract class Hasher {
-    protected __brand: never;
-    update(input: string): void;
-    digest(outputEncoding: BinaryEncoding): bytes;
-    digest(outputEncoding: StringEncoding): string;
-}
+           protected __brand: never;
+
+           /**
+            * Add more data to the string we want to create a hash of.
+            * @param input - Data to add.
+            */
+           update(input: string): void;
+
+           /**
+            * Return a digest from the data added so far.
+            * @param outputEncoding - Output encoding.
+            * @returns Digest of data added so far.
+            */
+           digest<OE extends OutputEncoding>(outputEncoding: OE): Output<OE>;
+       }
diff --git a/types/k6/encoding.d.ts b/types/k6/encoding.d.ts
@@ -1,4 +1,30 @@
+/*
+ * Encoding utilities.
+ * https://docs.k6.io/docs/k6encoding
+ */
+
+/**
+ * Base64 encode a string.
+ * https://docs.k6.io/docs/b64encode-input-encoding
+ * @param input - String to encode.
+ * @param encoding - Base64 variant.
+ * @returns Base64 encoded string.
+ * @public
+ */
 export function b64decode(input: string, encoding?: Base64Variant): string;
+
+/**
+ * Base64 decode a string.
+ * https://docs.k6.io/docs/b64decode-input-encoding
+ * @param input - Base64 encoded string.
+ * @param encoding - Base64 variant.
+ * @returns Decoded string.
+ * @public
+ */
 export function b64encode(input: string, encoding?: Base64Variant): string;
 
+/**
+ * Base64 variant.
+ * @public
+ */
 export type Base64Variant = 'std' | 'rawstd' | 'url' | 'rawurl';
diff --git a/types/k6/global.d.ts b/types/k6/global.d.ts
@@ -1,26 +1,98 @@
+/*
+ * Custom entities exposed in the global environment.
+ *
+ * The global environment changes with execution context. Some items are
+ * available only in the init context, others only during VU logic execution,
+ * others in both contexts. Comments note availability.
+ */
+
 import { bytes } from '.';
 
 export {};
 
 // Available without importing
 declare global {
-    // Init context only
+    // === Init context only ===
+    // -------------------------
+
+    /**
+     * Opens a file, reading all its contents into memory.
+     * https://docs.k6.io/docs/open-filepath-mode
+     * @param filePath - Path to file.
+     * @returns File contents decoded as UTF-8.
+     * @public
+     */
     function open(filePath: string): string;
+
+    /**
+     * Opens a file, reading all its contents into memory.
+     * https://docs.k6.io/docs/open-filepath-mode
+     * @param filePath - Path to file.
+     * @returns Binary file contents.
+     * @public
+     */
     function open(filePath: string, mode: 'b'): bytes;
 
-    // Init context and VU body
-    const __ENV: object;
+    // === Init context and VU logic ===
+    // ---------------------------------
+
+    /**
+     * Environment variables.
+     * https://docs.k6.io/docs/environment-variables
+     * @public
+     */
+    const __ENV: { [name: string]: string };
 
-    // VU body only
+    // === VU logic only ===
+    // ---------------------
+
+    /**
+     * Interface to system console.
+     * @public
+     */
     let console: Console;
-    const __VU: number; // Changes across VUs
-    const __ITER: number; // Changes across iterations
+
+    /**
+     * Current VU number.
+     * https://docs.k6.io/docs/execution-context-variables
+     * @public
+     */
+    const __VU: number;
+
+    /**
+     * Current iteration number.
+     * https://docs.k6.io/docs/execution-context-variables
+     * @public
+     */
+    const __ITER: number;
 }
 
+/** @public */
 interface Console {
-    debug(msg: any, ...fields: any[]): void;
-    error(msg: any, ...fields: any[]): void;
-    info(msg: any, ...fields: any[]): void;
-    log(msg: any, ...fields: any[]): void;
-    warn(msg: any, ...fields: any[]): void;
+    /** Log debug message. */
+    debug: Logger;
+
+    /** Log error message. */
+    error: Logger;
+
+    /** Log informational message. */
+    info: Logger;
+
+    /** Log message. */
+    log: Logger;
+
+    /** Log warning message. */
+    warn: Logger;
+}
+
+/**
+ * Log message procedure.
+ * @public
+ */
+interface Logger {
+    /**
+     * @param msg - Message to log.
+     * @param fields - Arbitrary data to attach to message.
+     */
+    (msg: any, ...fields: any[]): void;
 }