docs(preconditions): add code block

Author: TomokiMiyauci

preconditions/if_match.ts

@@ -15,7 +15,33 @@ import {
 import type { Precondition } from "../types.ts";
 import { ifMatch } from "./utils.ts";
 
-/** `If-Match` header field precondition. */
+/** `If-Match` header field precondition.
+ *
+ * @example
+ * ```ts
+ * import { IfMatch } from "https://deno.land/x/conditional_request_middleware@$VERSION/mod.ts";
+ * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * const precondition = new IfMatch();
+ * const request = new Request("<uri>", {
+ *   headers: { "if-match": "<strong:etag>" },
+ * });
+ * const selectedRepresentation = new Response("<content>", {
+ *   headers: { etag: "<weak:etag>" },
+ * });
+ * declare const evalResult: false;
+ *
+ * assertEquals(precondition.field, "if-match");
+ * assertEquals(
+ *   precondition.evaluate(request, selectedRepresentation),
+ *   evalResult,
+ * );
+ * assertEquals(
+ *   precondition.respond(request, selectedRepresentation, evalResult)?.status,
+ *   412,
+ * );
+ * ```
+ */
 export class IfMatch implements Precondition {
   field = ConditionalHeader.IfMatch;
 
@@ -36,7 +62,7 @@ export class IfMatch implements Precondition {
     _: unknown,
     response: Response,
     result: boolean,
-  ): undefined | Response {
+  ): Response | undefined {
     if (result) return;
 
     const headers = filterKeys(response.headers, not(isRepresentationHeader));

preconditions/if_modified_since.ts

@@ -16,7 +16,33 @@ import { isBannedHeader } from "../utils.ts";
 import { ifModifiedSince } from "./utils.ts";
 import type { Precondition } from "../types.ts";
 
-/** `If-Modified-Since` header field precondition. */
+/** `If-Modified-Since` header field precondition.
+ *
+ * @example
+ * ```ts
+ * import { IfModifiedSince } from "https://deno.land/x/conditional_request_middleware@$VERSION/mod.ts";
+ * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * const precondition = new IfModifiedSince();
+ * const request = new Request("<uri>", {
+ *   headers: { "if-modified-since": "<after:HTTP-date>" },
+ * });
+ * const selectedRepresentation = new Response("<content>", {
+ *   headers: { "last-modified": "<before:HTTP-date>" },
+ * });
+ * declare const evalResult: false;
+ *
+ * assertEquals(precondition.field, "if-modified-since");
+ * assertEquals(
+ *   precondition.evaluate(request, selectedRepresentation),
+ *   evalResult,
+ * );
+ * assertEquals(
+ *   precondition.respond(request, selectedRepresentation, evalResult)?.status,
+ *   304,
+ * );
+ * ```
+ */
 export class IfModifiedSince implements Precondition {
   field = ConditionalHeader.IfModifiedSince;
 

preconditions/if_none_match.ts

@@ -17,7 +17,33 @@ import type { Precondition } from "../types.ts";
 import { ifNoneMatch } from "./utils.ts";
 import { isBannedHeader } from "../utils.ts";
 
-/** `If-None-Match` header field precondition. */
+/** `If-None-Match` header field precondition.
+ *
+ * @example
+ * ```ts
+ * import { IfNoneMatch } from "https://deno.land/x/conditional_request_middleware@$VERSION/mod.ts";
+ * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * const precondition = new IfNoneMatch();
+ * const request = new Request("<uri>", {
+ *   headers: { "if-none-match": "<weak:etag>" },
+ * });
+ * const selectedRepresentation = new Response("<content>", {
+ *   headers: { etag: "<weak:etag>" },
+ * });
+ * declare const evalResult: false;
+ *
+ * assertEquals(precondition.field, "if-none-match");
+ * assertEquals(
+ *   precondition.evaluate(request, selectedRepresentation),
+ *   evalResult,
+ * );
+ * assertEquals(
+ *   precondition.respond(request, selectedRepresentation, evalResult)?.status,
+ *   304,
+ * );
+ * ```
+ */
 export class IfNoneMatch implements Precondition {
   field = ConditionalHeader.IfNoneMatch;
 

preconditions/if_range.ts

@@ -44,7 +44,34 @@ export function evaluateIfRange(
   return result.value;
 }
 
-/** `If-Range` header field precondition. */
+/** `If-Range` header field precondition.
+ *
+ * @example
+ * ```ts
+ * import { IfRange } from "https://deno.land/x/conditional_request_middleware@$VERSION/mod.ts";
+ * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * const precondition = new IfRange();
+ * const request = new Request("<uri>", {
+ *   headers: { "if-range": "<strong:etag>", range: "<range-unit>=<range-set>" },
+ * });
+ * const selectedRepresentation = new Response("<content>", {
+ *   headers: { etag: "<strong:etag>" },
+ * });
+ * declare const evalResult: false;
+ *
+ * assertEquals(precondition.field, "if-range");
+ * assertEquals(
+ *   precondition.evaluate(request, selectedRepresentation),
+ *   evalResult,
+ * );
+ * assertEquals(
+ *   (await precondition.respond(request, selectedRepresentation, evalResult))
+ *     ?.status,
+ *   206,
+ * );
+ * ```
+ */
 export class IfRange implements Precondition {
   #ranges: Iterable<Range>;
   field = ConditionalHeader.IfRange;

preconditions/if_unmodified_since.ts

@@ -13,7 +13,33 @@ import {
 import type { Precondition } from "../types.ts";
 import { ifUnmodifiedSince } from "./utils.ts";
 
-/** `If-Unmodified-Since` header field precondition. */
+/** `If-Unmodified-Since` header field precondition.
+ *
+ * @example
+ * ```ts
+ * import { IfUnmodifiedSince } from "https://deno.land/x/conditional_request_middleware@$VERSION/mod.ts";
+ * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * const precondition = new IfUnmodifiedSince();
+ * const request = new Request("<uri>", {
+ *   headers: { "if-unmodified-since": "<before:HTTP-date>" },
+ * });
+ * const selectedRepresentation = new Response("<content>", {
+ *   headers: { "last-modified": "<after:HTTP-date>" },
+ * });
+ * declare const evalResult: false;
+ *
+ * assertEquals(precondition.field, "if-unmodified-since");
+ * assertEquals(
+ *   precondition.evaluate(request, selectedRepresentation),
+ *   evalResult,
+ * );
+ * assertEquals(
+ *   precondition.respond(request, selectedRepresentation, evalResult)?.status,
+ *   412,
+ * );
+ * ```
+ */
 export class IfUnmodifiedSince implements Precondition {
   field = ConditionalHeader.IfUnmodifiedSince;