@reykjavik/webtools 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.9
+
+_2023-04-27_
+
+- `@reykjavik/webtools/http`
+  - feat: Add `toSec` TTL helper
+
 ## 0.1.7 – 0.1.8
 
 _2023-04-19_

package/README.md

@@ -19,6 +19,7 @@ yarn add @reykjavik/webtools
   - [Types for HTTP Status code groups](#types-for-http-status-code-groups)
   - [`cacheControl` helper](#cachecontrol-helper)
     - [Type `TTLConfig`](#type-ttlconfig)
+  - [`toSec` TTL helper](#tosec-ttl-helper)
 - [`@reykjavik/webtools/next/http`](#reykjavikwebtoolsnexthttp)
   - [`makeErrorizeAppHOC`](#makeerrorizeapphoc)
   - [`showErrorPage` helper](#showerrorpage-helper)
@@ -155,6 +156,22 @@ Allows setting a "must-revalidate" flag instead of the default "immutable". A
 value of `"normal"` omits the flagging and falls back to HTTP's default
 behavior.
 
+### `toSec` TTL helper
+
+**Syntax:** <code>toSec; (ttl: number | `${number}${'s'|'m'|'h'|'d'|'w'}`) =>
+number</code>
+
+Converts a `TTL` (max-age) value into seconds, and returns `0` for bad and/or
+negative input values.
+
+```js
+import type { toSec, TTL } from '@reykjavik/webtools/http';
+
+const ttl: TTL = '2h';
+
+const ttlSec = toSec(ttl);
+```
+
 ---
 
 ## `@reykjavik/webtools/next/http`

package/esm/http.d.ts

@@ -115,7 +115,7 @@ export type HTTP_CLIENT_ERROR_ALL = HTTP_CLIENT_ERROR | typeof HTTP_405_MethodNo
 export type HTTP_SERVER_ERROR_ALL = HTTP_SERVER_ERROR | typeof HTTP_501_NotImplemented | typeof HTTP_502_BadGateway | typeof HTTP_503_ServiceUnavailable | typeof HTTP_504_GatewayTimeout | typeof HTTP_505_HTTPVersionNotSupported | typeof HTTP_506_VariantAlsoNegotiates | typeof HTTP_510_NotExtended | typeof HTTP_511_NetworkAuthenticationRequired;
 export type HTTP_ERROR_ALL = HTTP_CLIENT_ERROR_ALL | HTTP_SERVER_ERROR_ALL;
 type TimeUnit = 's' | 'm' | 'h' | 'd' | 'w';
-type TTL = number | `${number}${TimeUnit}`;
+export type TTL = number | `${number}${TimeUnit}`;
 type TTLKeywords = 'permanent' | 'unset' | 'no-cache';
 type TTLObj = {
     /** Sets the cache `max-age=` for the resource. */
@@ -134,6 +134,13 @@ type TTLObj = {
  * @see https://github.com/reykjavikcity/webtools/tree/v0.1#type-ttlconfig
  */
 export type TTLConfig = TTL | TTLKeywords | TTLObj;
+/**
+ * Converts a `TTL` (max-age) value into seconds, and returns `0` for bad
+ * and/or negative input values.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#tosec-ttl-helper
+ */
+export declare const toSec: (ttl: TTL) => number;
 /**
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response

package/esm/http.js

@@ -110,16 +110,19 @@ const unitToSeconds = {
     d: 24 * 3600,
     w: 7 * 24 * 3600,
 };
-const toSec = (ttl) => {
-    if (ttl == null) {
-        return;
-    }
+/**
+ * Converts a `TTL` (max-age) value into seconds, and returns `0` for bad
+ * and/or negative input values.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#tosec-ttl-helper
+ */
+export const toSec = (ttl) => {
     if (typeof ttl === 'string') {
         const value = parseFloat(ttl);
         const factor = unitToSeconds[ttl.slice(-1)] || 1;
         ttl = value * factor;
     }
-    return !isNaN(ttl) ? ttl : undefined;
+    return Math.max(0, Math.round(ttl)) || 0;
 };
 const stabilities = {
     revalidate: ', must-revalidate',
@@ -163,22 +166,21 @@ export const cacheControl = (response, ttlCfg, eTag) => {
             maxAge = undefined;
         }
     }
-    maxAge = toSec(maxAge);
     if (maxAge == null) {
         response.removeHeader('Cache-Control');
         return;
     }
-    const sWR_ttl = toSec(opts.staleWhileRevalidate);
-    const sWR = sWR_ttl != null ? `, stale-while-revalidate=${sWR_ttl}` : '';
-    const sIE_ttl = toSec(opts.staleIfError);
-    const sIE = sIE_ttl != null ? `, stale-if-error=${sIE_ttl}` : '';
-    maxAge = Math.round(maxAge);
-    if (maxAge <= 0) {
+    maxAge = toSec(maxAge);
+    if (!maxAge) {
         setCC(response, 'no-cache');
         return;
     }
+    const sWR_ttl = toSec(opts.staleWhileRevalidate || 0);
+    const sWR = sWR_ttl ? `, stale-while-revalidate=${sWR_ttl}` : '';
+    const sIE_ttl = toSec(opts.staleIfError || 0);
+    const sIE = sIE_ttl ? `, stale-if-error=${sIE_ttl}` : '';
     const scope = opts.publ ? 'public' : 'private';
     const stability = (opts.stability && stabilities[opts.stability]) || stabilities.immutable;
-    eTag != null && response.setHeader('ETag', eTag);
     setCC(response, `${scope}, max-age=${maxAge + sWR + sIE + stability}`);
+    eTag != null && response.setHeader('ETag', eTag);
 };

package/http.d.ts

@@ -115,7 +115,7 @@ export type HTTP_CLIENT_ERROR_ALL = HTTP_CLIENT_ERROR | typeof HTTP_405_MethodNo
 export type HTTP_SERVER_ERROR_ALL = HTTP_SERVER_ERROR | typeof HTTP_501_NotImplemented | typeof HTTP_502_BadGateway | typeof HTTP_503_ServiceUnavailable | typeof HTTP_504_GatewayTimeout | typeof HTTP_505_HTTPVersionNotSupported | typeof HTTP_506_VariantAlsoNegotiates | typeof HTTP_510_NotExtended | typeof HTTP_511_NetworkAuthenticationRequired;
 export type HTTP_ERROR_ALL = HTTP_CLIENT_ERROR_ALL | HTTP_SERVER_ERROR_ALL;
 type TimeUnit = 's' | 'm' | 'h' | 'd' | 'w';
-type TTL = number | `${number}${TimeUnit}`;
+export type TTL = number | `${number}${TimeUnit}`;
 type TTLKeywords = 'permanent' | 'unset' | 'no-cache';
 type TTLObj = {
     /** Sets the cache `max-age=` for the resource. */
@@ -134,6 +134,13 @@ type TTLObj = {
  * @see https://github.com/reykjavikcity/webtools/tree/v0.1#type-ttlconfig
  */
 export type TTLConfig = TTL | TTLKeywords | TTLObj;
+/**
+ * Converts a `TTL` (max-age) value into seconds, and returns `0` for bad
+ * and/or negative input values.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#tosec-ttl-helper
+ */
+export declare const toSec: (ttl: TTL) => number;
 /**
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response

package/http.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cacheControl = exports.HTTP_511_NetworkAuthenticationRequired = exports.HTTP_510_NotExtended = exports.HTTP_506_VariantAlsoNegotiates = exports.HTTP_505_HTTPVersionNotSupported = exports.HTTP_504_GatewayTimeout = exports.HTTP_503_ServiceUnavailable = 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_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_206_PartialContent = exports.HTTP_204_NoContent = exports.HTTP_203_NonAuthoritativeInformation = exports.HTTP_202_Accepted = exports.HTTP_201_Created = exports.HTTP_200_OK = exports.HTTP_101_SwitchingProtocols = exports.HTTP_100_Continue = void 0;
+exports.cacheControl = exports.toSec = exports.HTTP_511_NetworkAuthenticationRequired = exports.HTTP_510_NotExtended = exports.HTTP_506_VariantAlsoNegotiates = exports.HTTP_505_HTTPVersionNotSupported = exports.HTTP_504_GatewayTimeout = exports.HTTP_503_ServiceUnavailable = 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_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_206_PartialContent = exports.HTTP_204_NoContent = exports.HTTP_203_NonAuthoritativeInformation = exports.HTTP_202_Accepted = exports.HTTP_201_Created = exports.HTTP_200_OK = exports.HTTP_101_SwitchingProtocols = exports.HTTP_100_Continue = void 0;
 // INFORMATION
 /** The client should continue the request or ignore the response if the request is already finished. */
 exports.HTTP_100_Continue = 100;
@@ -113,17 +113,21 @@ const unitToSeconds = {
     d: 24 * 3600,
     w: 7 * 24 * 3600,
 };
+/**
+ * Converts a `TTL` (max-age) value into seconds, and returns `0` for bad
+ * and/or negative input values.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#tosec-ttl-helper
+ */
 const toSec = (ttl) => {
-    if (ttl == null) {
-        return;
-    }
     if (typeof ttl === 'string') {
         const value = parseFloat(ttl);
         const factor = unitToSeconds[ttl.slice(-1)] || 1;
         ttl = value * factor;
     }
-    return !isNaN(ttl) ? ttl : undefined;
+    return Math.max(0, Math.round(ttl)) || 0;
 };
+exports.toSec = toSec;
 const stabilities = {
     revalidate: ', must-revalidate',
     immutable: ', immutable',
@@ -166,23 +170,22 @@ const cacheControl = (response, ttlCfg, eTag) => {
             maxAge = undefined;
         }
     }
-    maxAge = toSec(maxAge);
     if (maxAge == null) {
         response.removeHeader('Cache-Control');
         return;
     }
-    const sWR_ttl = toSec(opts.staleWhileRevalidate);
-    const sWR = sWR_ttl != null ? `, stale-while-revalidate=${sWR_ttl}` : '';
-    const sIE_ttl = toSec(opts.staleIfError);
-    const sIE = sIE_ttl != null ? `, stale-if-error=${sIE_ttl}` : '';
-    maxAge = Math.round(maxAge);
-    if (maxAge <= 0) {
+    maxAge = (0, exports.toSec)(maxAge);
+    if (!maxAge) {
         setCC(response, 'no-cache');
         return;
     }
+    const sWR_ttl = (0, exports.toSec)(opts.staleWhileRevalidate || 0);
+    const sWR = sWR_ttl ? `, stale-while-revalidate=${sWR_ttl}` : '';
+    const sIE_ttl = (0, exports.toSec)(opts.staleIfError || 0);
+    const sIE = sIE_ttl ? `, stale-if-error=${sIE_ttl}` : '';
     const scope = opts.publ ? 'public' : 'private';
     const stability = (opts.stability && stabilities[opts.stability]) || stabilities.immutable;
-    eTag != null && response.setHeader('ETag', eTag);
     setCC(response, `${scope}, max-age=${maxAge + sWR + sIE + stability}`);
+    eTag != null && response.setHeader('ETag', eTag);
 };
 exports.cacheControl = cacheControl;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.8",
+	"version": "0.1.9",
 	"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",