@reykjavik/webtools 0.1.27 → 0.1.29

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.29
+
+_2024-08-26_
+
+- `@reykjavik/webtools/http`:
+  - feat: Add `cacheControlHeaders` helper that returns a `HeadersInit` object
+  - fix: `cacheControl` with `maxAge: 'unset'` didn't delete `X-Cache-Control`
+    in dev mode
+
+## 0.1.28
+
+_2024-08-26_
+
+- `@reykjavik/webtools/http`:
+  - feat: `cacheControl` now also accepts `Map<string, string>` for headers
+
 ## 0.1.27
 
 _2024-07-18_

package/README.md

@@ -20,6 +20,7 @@ bun add @reykjavik/webtools
   - [HTTP Status Codes](#http-status-codes)
   - [Types for HTTP Status code groups](#types-for-http-status-code-groups)
   - [`cacheControl` helper](#cachecontrol-helper)
+  - [`cacheControlHeaders` helper](#cachecontrolheaders-helper)
     - [Type `TTLConfig`](#type-ttlconfig)
   - [`toSec` TTL helper](#tosec-ttl-helper)
 - [`@reykjavik/webtools/async`](#reykjavikwebtoolsasync)
@@ -112,10 +113,10 @@ codes, are also available:
 ### `cacheControl` helper
 
 **Syntax:**
-`cacheConrol(response: ServerResponse | { res: ServerResponse }, ttlCfg: TTLConfig, eTag?: string|number): void`
+`cacheConrol(response: ServerResponse | Response | Map<string, string> | { res: ServerResponse | Response }, ttlCfg: TTLConfig, eTag?: string|number): void`
 
 Use this function to quickly set the `Cache-Control` header with a `max-age=`
-on a HTTP response.
+on a HTTP response (or a `Map` object representing response headers).
 
 ```js
 import { cacheControl } from '@reykjavik/webtools/http';
@@ -131,6 +132,27 @@ The directives `private` and `immutable` are used by by default.
 Use the optional `eTag` parameter if you intend to
 [handle conditional requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests).
 
+### `cacheControlHeaders` helper
+
+**Syntax:**
+`cacheControlHeaders(ttlCfg: TTLConfig, eTag?: string|number): Record<string, string>`
+
+Similar to the [`cacheControl` helper](#cachecontrol-helper), but returns an
+plain object with the headers for use in situations where `HeadersInit` object
+are expected.
+
+```js
+import { cacheControlHeaders } from '@reykjavik/webtools/http';
+
+const response = new Response('Hello, World!', {
+  headers: cacheControlHeaders('4h'),
+});
+```
+
+```js
+
+```
+
 #### Type `TTLConfig`
 
 ```js

package/esm/http.d.ts

@@ -168,15 +168,23 @@ type ServerResponseStub = Pick<ServerResponse, 'setHeader' | 'getHeader' | 'remo
     headers?: Record<string, string | Array<string>>;
 };
 type ResponseStub = {
-    headers: Pick<Headers, 'set' | 'get' | 'delete' | 'append'>;
+    headers: Pick<Headers, 'set' | 'get' | 'delete'>;
 };
 /**
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#getcssbundleurl
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrol-helper
  */
-export declare const cacheControl: (response: ServerResponseStub | ResponseStub | {
+export declare const cacheControl: (response: ServerResponseStub | ResponseStub | Map<string, string> | {
     res: ServerResponseStub | ResponseStub;
 }, ttlCfg: TTLConfig, eTag?: string | number) => void;
+/**
+ * Generates a Record with `Cache-Control` and `ETag` headers, for use in
+ * situations requiring a `HeadersInit` compatible object.
+ *
+ * Accepts the same arguments as `cacheControl()`.
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrolheaders-helper
+ */
+export declare const cacheControlHeaders: (ttlCfg: TTLConfig, eTag?: string | number) => Record<string, string>;
 export {};

package/esm/http.js

@@ -147,6 +147,9 @@ export const toSec = (ttl) => {
     return Math.max(0, Math.round(ttl)) || 0;
 };
 const toRespnseStubHeaders = (response) => {
+    if (response instanceof Map) {
+        return response;
+    }
     if ('headers' in response && !('setHeader' in response)) {
         return response.headers;
     }
@@ -159,15 +162,6 @@ const toRespnseStubHeaders = (response) => {
             return val != null ? `${val}` : null;
         },
         set: (name, value) => response.setHeader(name, value),
-        append: (name, value) => {
-            const existing = response.getHeader(name);
-            if (existing) {
-                response.setHeader(name, `${existing}, ${value}`);
-            }
-            else {
-                response.setHeader(name, value);
-            }
-        },
         delete: (name) => response.removeHeader(name),
     };
 };
@@ -194,7 +188,7 @@ const setCC = (response, cc) => {
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#getcssbundleurl
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrol-helper
  */
 // eslint-disable-next-line complexity
 export const cacheControl = (response, ttlCfg, eTag) => {
@@ -215,7 +209,7 @@ export const cacheControl = (response, ttlCfg, eTag) => {
         }
     }
     if (maxAge == null) {
-        toRespnseStubHeaders(response).delete('Cache-Control');
+        setCC(response, undefined);
         return;
     }
     maxAge = toSec(maxAge);
@@ -232,3 +226,15 @@ export const cacheControl = (response, ttlCfg, eTag) => {
     setCC(response, `${scope}, max-age=${maxAge + sWR + sIE + stability}`);
     eTag != null && toRespnseStubHeaders(response).set('ETag', String(eTag));
 };
+/**
+ * Generates a Record with `Cache-Control` and `ETag` headers, for use in
+ * situations requiring a `HeadersInit` compatible object.
+ *
+ * Accepts the same arguments as `cacheControl()`.
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrolheaders-helper
+ */
+export const cacheControlHeaders = (ttlCfg, eTag) => {
+    const headers = new Map();
+    cacheControl(headers, ttlCfg, eTag);
+    return Object.fromEntries(headers);
+};

package/http.d.ts

@@ -168,15 +168,23 @@ type ServerResponseStub = Pick<ServerResponse, 'setHeader' | 'getHeader' | 'remo
     headers?: Record<string, string | Array<string>>;
 };
 type ResponseStub = {
-    headers: Pick<Headers, 'set' | 'get' | 'delete' | 'append'>;
+    headers: Pick<Headers, 'set' | 'get' | 'delete'>;
 };
 /**
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#getcssbundleurl
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrol-helper
  */
-export declare const cacheControl: (response: ServerResponseStub | ResponseStub | {
+export declare const cacheControl: (response: ServerResponseStub | ResponseStub | Map<string, string> | {
     res: ServerResponseStub | ResponseStub;
 }, ttlCfg: TTLConfig, eTag?: string | number) => void;
+/**
+ * Generates a Record with `Cache-Control` and `ETag` headers, for use in
+ * situations requiring a `HeadersInit` compatible object.
+ *
+ * Accepts the same arguments as `cacheControl()`.
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrolheaders-helper
+ */
+export declare const cacheControlHeaders: (ttlCfg: TTLConfig, eTag?: string | number) => Record<string, string>;
 export {};

package/http.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HTTP_502_BadGateway = exports.HTTP_501_NotImplemented = exports.HTTP_500_InternalServerError = exports.HTTP_451_UnavailableForLegalReasons = exports.HTTP_431_RequestHeaderFieldsTooLarge = exports.HTTP_429_TooManyRequests = exports.HTTP_428_PreconditionRequired = exports.HTTP_426_UpgradeRequired = exports.HTTP_424_FailedDependency = exports.HTTP_423_Locked = exports.HTTP_422_UnprocessableContent = exports.HTTP_421_MisdirectedRequest = exports.HTTP_418_ImATeapot = exports.HTTP_417_ExpectationFailed = exports.HTTP_416_RangeNotSatisfiable = exports.HTTP_415_UnsupportedMediaType = exports.HTTP_414_URITooLong = exports.HTTP_413_PayloadTooLarge = exports.HTTP_412_PreconditionFailed = exports.HTTP_411_LengthRequired = exports.HTTP_410_Gone = exports.HTTP_409_Conflict = exports.HTTP_408_RequestTimeout = exports.HTTP_407_ProxyAuthenticationRequired = exports.HTTP_406_NotAcceptable = exports.HTTP_405_MethodNotAllowed = exports.HTTP_404_NotFound = exports.HTTP_403_Forbidden = exports.HTTP_401_Unauthorized = exports.HTTP_400_BadRequest = exports.HTTP_308_PermanentRedirect = exports.HTTP_307_TemporaryRedirect = exports.HTTP_304_NotModified = exports.HTTP_303_SeeOther = exports.HTTP_302_Found = exports.HTTP_301_MovedPermanently = exports.HTTP_226_IMUsed = exports.HTTP_208_AlreadyReported = exports.HTTP_207_MultiStatus = exports.HTTP_206_PartialContent = exports.HTTP_205_ResetContent = exports.HTTP_204_NoContent = exports.HTTP_203_NonAuthoritativeInformation = exports.HTTP_202_Accepted = exports.HTTP_201_Created = exports.HTTP_200_OK = exports.HTTP_103_EarlyHints = exports.HTTP_102_Processing = exports.HTTP_101_SwitchingProtocols = exports.HTTP_100_Continue = void 0;
-exports.cacheControl = exports.toSec = exports.HTTP_511_NetworkAuthenticationRequired = exports.HTTP_510_NotExtended = exports.HTTP_508_LoopDetected = exports.HTTP_507_InsufficientStorage = exports.HTTP_506_VariantAlsoNegotiates = exports.HTTP_505_HTTPVersionNotSupported = exports.HTTP_504_GatewayTimeout = exports.HTTP_503_ServiceUnavailable = void 0;
+exports.cacheControlHeaders = exports.cacheControl = exports.toSec = exports.HTTP_511_NetworkAuthenticationRequired = exports.HTTP_510_NotExtended = exports.HTTP_508_LoopDetected = exports.HTTP_507_InsufficientStorage = exports.HTTP_506_VariantAlsoNegotiates = exports.HTTP_505_HTTPVersionNotSupported = exports.HTTP_504_GatewayTimeout = exports.HTTP_503_ServiceUnavailable = void 0;
 // INFORMATION
 /** The client should continue the request or ignore the response if the request is already finished. */
 exports.HTTP_100_Continue = 100;
@@ -152,6 +152,9 @@ const toSec = (ttl) => {
 };
 exports.toSec = toSec;
 const toRespnseStubHeaders = (response) => {
+    if (response instanceof Map) {
+        return response;
+    }
     if ('headers' in response && !('setHeader' in response)) {
         return response.headers;
     }
@@ -164,15 +167,6 @@ const toRespnseStubHeaders = (response) => {
             return val != null ? `${val}` : null;
         },
         set: (name, value) => response.setHeader(name, value),
-        append: (name, value) => {
-            const existing = response.getHeader(name);
-            if (existing) {
-                response.setHeader(name, `${existing}, ${value}`);
-            }
-            else {
-                response.setHeader(name, value);
-            }
-        },
         delete: (name) => response.removeHeader(name),
     };
 };
@@ -199,7 +193,7 @@ const setCC = (response, cc) => {
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#getcssbundleurl
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrol-helper
  */
 // eslint-disable-next-line complexity
 const cacheControl = (response, ttlCfg, eTag) => {
@@ -220,7 +214,7 @@ const cacheControl = (response, ttlCfg, eTag) => {
         }
     }
     if (maxAge == null) {
-        toRespnseStubHeaders(response).delete('Cache-Control');
+        setCC(response, undefined);
         return;
     }
     maxAge = (0, exports.toSec)(maxAge);
@@ -238,3 +232,16 @@ const cacheControl = (response, ttlCfg, eTag) => {
     eTag != null && toRespnseStubHeaders(response).set('ETag', String(eTag));
 };
 exports.cacheControl = cacheControl;
+/**
+ * Generates a Record with `Cache-Control` and `ETag` headers, for use in
+ * situations requiring a `HeadersInit` compatible object.
+ *
+ * Accepts the same arguments as `cacheControl()`.
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cachecontrolheaders-helper
+ */
+const cacheControlHeaders = (ttlCfg, eTag) => {
+    const headers = new Map();
+    (0, exports.cacheControl)(headers, ttlCfg, eTag);
+    return Object.fromEntries(headers);
+};
+exports.cacheControlHeaders = cacheControlHeaders;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.27",
+	"version": "0.1.29",
 	"description": "Misc. JS/TS helpers used by Reykjavík City's web dev teams.",
 	"main": "index.js",
 	"repository": "ssh://git@github.com:reykjavikcity/webtools.git",