bump version

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@char/ngx",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "WTFPL",
   "exports": "./ngx.ts"
 }

ngx.ts

@@ -1,4 +1,4 @@
-const NGX_VERSION = "0.2.1";
+const NGX_VERSION = "0.2.2";
 
 type ConfigNode = ConfigStatement | ConfigBlock | ConfigBreak | ConfigFile;
 
@@ -84,6 +84,23 @@ function conform(looseNode: LooseConfigNode): ConfigNode[] {
   return [looseNode];
 }
 
+/**
+ * create nginx config nodes. behavior depends on arguments:
+ *
+ * - no args - ConfigBreak
+ * - value only - ConfigStatement
+ * - value + children - ConfigBlock
+ * - children only - ConfigFile
+ *
+ * accept strings, ConfigNodes, or nested arrays that flatten automatically.
+ *
+ * ```ts
+ * ngx() // ConfigBreak
+ * ngx("worker_processes auto") // ConfigStatement
+ * ngx("location /", ["proxy_pass http://backend"]) // ConfigBlock
+ * ngx(["server { ... }", "server { ... }"]) // ConfigFile
+ * ```
+ */
 export function ngx(value?: string, children?: LooseConfigNode[]): ConfigNode {
   const hasValue = value !== undefined && value !== "";
   const hasChildren = children !== undefined;
@@ -101,6 +118,16 @@ export function ngx(value?: string, children?: LooseConfigNode[]): ConfigNode {
   throw new Error("unreachable");
 }
 
+/**
+ * create ssl listen directives for ipv4/ipv6 with http/2 enabled.
+ *
+ * extras modify the listen directives.
+ *
+ * ```ts
+ * listen() // listen 443 ssl, listen [::]:443 ssl, http2 on
+ * listen("default_server") // includes "default_server"
+ * ```
+ */
 export const listen = (...extras: string[]) =>
   conform([
     `listen 443 ${["ssl", ...extras].join(" ")}`,
@@ -108,9 +135,39 @@ export const listen = (...extras: string[]) =>
     `http2 on`,
   ]);
 
+/**
+ * create http/3 (quic) listen directives (+ supporting alt-svc header).
+ */
+export const http3 = (
+  opts: {
+    /** max age for alt-svc header */ ma?: number;
+  } = {},
+) =>
+  conform([
+    "listen 443 quic reuseport",
+    "listen [::]:443 quic reuseport",
+    `add_header Alt-Svc 'h3=":443"; ma=${opts.ma ?? 86400}'`,
+  ]);
+
+/**
+ * create a server_name nginx directive.
+ *
+ * ```ts
+ * serverName("example.com") // "server_name example.com;"
+ * ```
+ */
 export const serverName = (name: string) =>
   new ConfigStatement(`server_name ${name}`);
 
+/**
+ * create ssl certificate directives for let's encrypt certificates.
+ *
+ * ```ts
+ * letsEncrypt("example.com")
+ * // ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem
+ * // ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem
+ * ```
+ */
 export const letsEncrypt = (
   domain: string,
   liveDir = "/etc/letsencrypt/live",
@@ -121,7 +178,17 @@ export const letsEncrypt = (
   ]);
 
 // the default export is both the ngx function and a namespace:
+/**
+ * use as a function to create config nodes, or access helpers.
+ *
+ * ```ts
+ * import ngx from './ngx';
+ * const config = ngx("location /", ["proxy_pass http://backend"]);
+ * console.log(ngx.NGX_VERSION);
+ * const ssl = ngx.letsEncrypt("example.com");
+ * ```
+ */
 export default Object.assign(
   (value?: string, children?: LooseConfigNode[]) => ngx(value, children),
-  { NGX_VERSION, listen, letsEncrypt, serverName },
+  { NGX_VERSION, listen, letsEncrypt, serverName, http3 },
 );