@tusbar/cache-control - npm Package Compare versions

Comparing version 0.6.0 to 0.6.1

index.d.ts

@@ -1,18 +0,315 @@
-declare interface ICacheControl {
-  maxAge?: number | null;
-  sharedMaxAge?: number | null;
-  maxStale?: boolean | null;
-  maxStaleDuration?: number | null;
-  minFresh?: number | null;
-  immutable?: boolean | null;
-  mustRevalidate?: boolean | null;
-  noCache?: boolean | null;
-  noStore?: boolean | null;
-  noTransform?: boolean | null;
-  onlyIfCached?: boolean | null;
-  private?: boolean | null;
-  proxyRevalidate?: boolean | null;
-  public?: boolean | null;
-  staleWhileRevalidate?: number | null;
-  staleIfError?: number | null;
+/**
+ * The Cache-Control HTTP header field holds directives (instructions)
+ * — in both requests and responses — that control caching in browsers
+ * and shared caches (e.g. Proxies, CDNs).
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+ */
+export declare class CacheControl {
+  /**
+   * The max-age=N response directive indicates that the response
+   * remains fresh until N seconds after the response is generated.
+   *
+   * ```txt
+   * Cache-Control: max-age=604800
+   * ```
+   *
+   * Indicates that caches can store this response and reuse it for
+   * subsequent requests while it's fresh.
+   *
+   * Note that max-age is not the elapsed time since the response was
+   * received, but instead the elapsed time since the response was
+   * generated on the origin server. So if the other cache(s) on the
+   * path the response takes store it for 100 seconds (indicated using
+   * the Age response header field), the browser cache would deduct
+   * 100 seconds from its freshness lifetime.
+   *
+   * ```txt
+   * Cache-Control: max-age=604800
+   * Age: 100
+   * ```
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#max-age
+   */
+  maxAge?: number | null
+  /**
+   * The s-maxage response directive also indicates how long the
+   * response is fresh for (similar to max-age) — but it is specific
+   * to shared caches, and they will ignore max-age when it is present.
+   *
+   * ```txt
+   * Cache-Control: s-maxage=604800
+   * ```
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#s-maxage
+   */
+  sharedMaxAge?: number | null
+  /**
+   * The max-stale=N request directive indicates that the client
+   * allows a stored response that is stale within N seconds.
+   *
+   * ```txt
+   * Cache-Control: max-stale=3600
+   * ```
+   *
+   * In the case above, if the response with Cache-Control:
+   * max-age=604800 was stored on caches 3 hours ago, the cache
+   * couldn't reuse that response.
+   *
+   * Clients can use this header when the origin server is down or too
+   * slow and can accept cached responses from caches even if they are
+   * a bit old.
+   *
+   * Note that the major browsers do not support requests with max-stale.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#max-stale
+   */
+  maxStale?: boolean | null
+  /**
+   * The max-stale=N request directive indicates that the client
+   * allows a stored response that is stale within N seconds.
+   *
+   * ```txt
+   * Cache-Control: max-stale=3600
+   * ```
+   *
+   * In the case above, if the response with Cache-Control:
+   * max-age=604800 was stored on caches 3 hours ago, the cache
+   * couldn't reuse that response.
+   *
+   * Clients can use this header when the origin server is down or too
+   * slow and can accept cached responses from caches even if they are
+   * a bit old.
+   *
+   * Note that the major browsers do not support requests with max-stale.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#max-stale
+   */
+  maxStaleDuration?: number | null
+  /**
+   * The min-fresh=N request directive indicates that the client
+   * allows a stored response that is fresh for at least N seconds.
+   *
+   * ```txt
+   * Cache-Control: min-fresh=600
+   * ```
+   *
+   * In the case above, if the response with Cache-Control:
+   * max-age=3600 was stored in caches 51 minutes ago, the cache
+   * couldn't reuse that response.
+   *
+   * Clients can use this header when the user requires the response
+   * to not only be fresh, but also requires that it won't be updated
+   * for a period of time.
+   *
+   * Note that the major browsers do not support requests with min-fresh.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#min-fresh
+   */
+  minFresh?: number | null
+  /**
+   * The immutable response directive indicates that the response will
+   * not be updated while it's fresh.
+   *
+   * ```txt
+   * Cache-Control: public, max-age=604800, immutable
+   * ```
+   *
+   * A modern best practice for static resources is to include
+   * version/hashes in their URLs, while never modifying the resources
+   * — but instead, when necessary, updating the resources with newer
+   * versions that have new version-numbers/hashes, so that their URLs
+   * are different. That’s called the cache-busting pattern.
+   *
+   * ```html
+   * <script src=https://example.com/react.0.0.0.js></script>
+   * ```
+   *
+   * When a user reloads the browser, the browser will send
+   * conditional requests for validating to the origin server. But
+   * it's not necessary to revalidate those kinds of static resources
+   * even when a user reloads the browser, because they're never
+   * modified. immutable tells a cache that the response is immutable
+   * while it's fresh, and avoids those kinds of unnecessary
+   * conditional requests to the server.
+   *
+   * When you use a cache-busting pattern for resources and apply them
+   * to a long max-age, you can also add immutable to avoid revalidation.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#immutable
+   */
+  immutable?: boolean | null
+  /**
+   * The must-revalidate response directive indicates that the
+   * response can be stored in caches and can be reused while fresh.
+   * Once it becomes stale, it must be validated with the origin
+   * server before reuse.
+   *
+   * Typically, must-revalidate is used with max-age.
+   *
+   * ```txt
+   * Cache-Control: max-age=604800, must-revalidate
+   * ```
+   *
+   * HTTP allows caches to reuse stale responses when they are
+   * disconnected from the origin server. must-revalidate is a way to
+   * prevent that, so that the cache either revalidates the stored
+   * response with the origin server, or if that's not possible it
+   * generates a 504 (Gateway Timeout) response.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#must-revalidate
+   */
+  mustRevalidate?: boolean | null
+  /**
+   * The no-cache response directive indicates that the response can
+   * be stored in caches, but must be validated with the origin server
+   * before each reuse — even when the cache is disconnected from the
+   * origin server.
+   *
+   * ```txt
+   * Cache-Control: no-cache
+   * ```
+   *
+   * If you want caches to always check for content updates while
+   * reusing stored content when it hasn't changed, no-cache is the
+   * directive to use. It does this by requiring caches to revalidate
+   * each request with the origin server.
+   *
+   * Note that no-cache does not mean "don't cache". no-cache allows
+   * caches to store a response, but requires them to revalidate it
+   * before reuse. If the sense of "don't cache" that you want is
+   * actually "don't store", then no-store is the directive to use.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#no-cache
+   */
+  noCache?: boolean | null
+  /**
+   * The no-store response directive indicates that any caches of any
+   * kind (private or shared) should not store this response.
+   *
+   * ```txt
+   * Cache-Control: no-store
+   * ```
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#no-store
+   */
+  noStore?: boolean | null
+  /**
+   * Some intermediaries transform content for various reasons. For
+   * example, some convert images to reduce transfer size. In some
+   * cases, this is undesirable for the content provider.
+   *
+   * No-transform indicates that any intermediary (regardless of
+   * whether it implements a cache) shouldn't transform the response contents.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#no-transform
+   */
+  noTransform?: boolean | null
+  /**
+   * The client indicates that cache should obtain an already-cached
+   * response. If a cache has stored a response, it’s reused.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#only-if-cached
+   */
+  onlyIfCached?: boolean | null
+  /**
+   * The private response directive indicates that the response can be
+   * stored only in a private cache (e.g. local caches in browsers).
+   *
+   * ```txt
+   * Cache-Control: private
+   * ```
+   *
+   * You should add the private directive for user-personalized
+   * content — in particular, responses received after login, and
+   * sessions managed via cookies.
+   *
+   * If you forget to add private to a response with personalized
+   * content, then that response can be stored in a shared cache and
+   * end up being used by multiple users, which can cause personal
+   * information to leak.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#private
+   */
+  private?: boolean | null
+  /**
+   * The proxy-revalidate response directive is the equivalent of
+   * must-revalidate, but specifically for shared caches only.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#proxy-revalidate
+   */
+  proxyRevalidate?: boolean | null
+  /**
+   * Responses for requests with Authorization header fields must not
+   * be stored in a shared cache. But the public directive will cause
+   * such responses to be stored in a shared cache.
+   *
+   * ```txt
+   * Cache-Control: public
+   * ```
+   *
+   * In general, when pages are under Basic Auth or Digest Auth, the
+   * browser sends requests with the Authorization header. That means
+   * the response is access-controlled for restricted users (who have
+   * accounts), and it's fundamentally not shared-cacheable, even if
+   * it has max-age.
+   *
+   * You can use the public directive to unlock that restriction.
+   *
+   * ```txt
+   * Cache-Control: public, max-age=604800
+   * ```
+   *
+   * Note that, s-maxage or must-revalidate also unlock that restriction.
+   *
+   * If a request doesn’t have an Authorization header, or you are
+   * already using s-maxage or must-revalidate in the response, then
+   * you don't need to use public.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#public
+   */
+  public?: boolean | null
+  /**
+   * The stale-while-revalidate response directive indicates that the
+   * cache could reuse a stale response while it revalidates it to a cache.
+   *
+   * ```txt
+   * Cache-Control: max-age=604800, stale-while-revalidate=86400
+   * ```
+   *
+   * In the example above, the response is fresh for 7 days (604800s).
+   * After 7 days, it becomes stale but the cache is allowed to reuse
+   * it for any requests that are made in the following day (86400s) —
+   * provided that they revalidate the response in the background.
+   *
+   * Revalidation will make the cache be fresh again, so it appears to
+   * clients that it was always fresh during that period — effectively
+   * hiding the latency penalty of revalidation from them.
+   *
+   * If no request happened during that period, the cache became stale
+   * and the next request will revalidate normally.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-while-revalidate
+   */
+  staleWhileRevalidate?: number | null
+  /**
+   * The stale-if-error response directive indicates that the cache
+   * can reuse a stale response when an origin server responds with an
+   * error (500, 502, 503, or 504).
+   *
+   * ```txt
+   * Cache-Control: max-age=604800, stale-if-error=86400
+   * ```
+   *
+   * In the example above, the response is fresh for 7 days (604800s).
+   * After 7 days it becomes stale, but it can be used for an extra 1
+   * day (86400s) if the server responds with an error.
+   *
+   * After a period of time, the stored response became stale
+   * normally. That means the client will receive an error response
+   * as-is if the origin server sends it.
+   *
+   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-if-error
+   */
+  staleIfError?: number | null
 }
@@ -23,15 +320,15 @@
  * by the string.
+ *
  * @param header The string to parse
  * @returns The JavaScript value or object described
-*/
-declare function parse(header: string): ICacheControl
+ */
+export declare function parse(header: string): CacheControl
 
 /**
- * Formats a Cache Control Header, constructing string from JavaScript object
- * by the string.
+ * Formats a Cache Control Header, constructing string from JavaScript
+ * object by the string.
+ *
  * @param header The string to parse
  * @returns The JavaScript value or object described
-*/
-declare function format(cc: ICacheControl): string
-
-export {ICacheControl, parse, format}
+ */
+declare function format(cc: CacheControl): string

index.js

@@ -18,3 +18,3 @@ const HEADER_REGEXP = /([a-zA-Z][a-zA-Z_-]*)\s*(?:=(?:"([^"]*)"|([^ \t",;]*)))?/g
   staleWhileRevalidate: 'stale-while-revalidate',
-  staleIfError: 'stale-if-error'
+  staleIfError: 'stale-if-error',
 }
@@ -194,3 +194,3 @@
   parse,
-  format
+  format,
 }

package.json

 {
   "name": "@tusbar/cache-control",
   "public": true,
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Format and parse HTTP Cache-Control header",
-  "main": "index.js",
+  "main": "./index.js",
+  "types": "./index.d.ts",
   "scripts": {
-    "test": "nyc ava"
+    "test": "jest"
   },
@@ -23,15 +24,22 @@ "keywords": [
   "devDependencies": {
-    "ava": "^3.2.0",
-    "codecov": "^3.0.0",
-    "lerna-changelog": "1.0.1",
-    "nyc": "^15.0.0",
-    "xo": "^0.39.1"
+    "@bizon/semantic-release-config": "^1.1.0",
+    "jest": "^27.4.0",
+    "jest-junit": "^13.0.0",
+    "semantic-release": "^18.0.1",
+    "xo": "^0.47.0"
   },
-  "nyc": {
-    "reporter": [
+  "jest": {
+    "testMatch": [
+      "<rootDir>/__tests__/*.js"
+    ],
+    "transform": {},
+    "collectCoverage": true,
+    "collectCoverageFrom": [
+      "index.js"
+    ],
+    "coverageReporters": [
       "lcov",
-      "text"
+      "text-summary"
     ]
   },
-  "types": "./index.d.ts",
   "xo": {
@@ -41,18 +49,17 @@ "semicolon": false,
     "rules": {
-      "unicorn/no-array-reduce": "off"
-    }
+      "unicorn/no-array-reduce": "off",
+      "unicorn/prefer-module": "off"
+    },
+    "overrides": [
+      {
+        "files": "__tests__/*.js",
+        "envs": [
+          "jest"
+        ]
+      }
+    ]
   },
-  "changelog": {
-    "cacheDir": ".changelog",
-    "labels": {
-      "bug": ":bug: Bug Fix",
-      "build": ":building_construction: Build Process",
-      "cleanup": ":shower: Cleanup",
-      "documentation": ":memo: Documentation",
-      "enhancement": ":rocket: Enhancement",
-      "performance": ":racehorse: Performance",
-      "security": ":policeman: Security"
-    },
-    "repo": "tusbar/cache-control"
+  "release": {
+    "extends": "@bizon/semantic-release-config"
   }
 }

README.md

@@ -1,2 +0,2 @@
-# cache-control [![CircleCI](https://circleci.com/gh/tusbar/cache-control.svg?style=svg)](https://circleci.com/gh/tusbar/cache-control)
+# cache-control
 
@@ -6,6 +6,10 @@ > Format and parse HTTP Cache-Control header
 [![npm version](https://badgen.net/npm/v/@tusbar/cache-control)](https://www.npmjs.com/package/@tusbar/cache-control)
-[![dependencies Status](https://badgen.net/david/dep/tusbar/cache-control)](https://david-dm.org/tusbar/cache-control)
 [![codecov](https://badgen.net/codecov/c/github/tusbar/cache-control)](https://codecov.io/gh/tusbar/cache-control)
 [![XO code style](https://badgen.net/badge/code%20style/XO/cyan)](https://github.com/xojs/xo)
 
+## CI
+
+[![Tests](https://github.com/tusbar/cache-control/actions/workflows/tests.yml/badge.svg)](https://github.com/tusbar/cache-control/actions/workflows/tests.yml)
+[![Release](https://github.com/tusbar/cache-control/actions/workflows/release.yml/badge.svg)](https://github.com/tusbar/cache-control/actions/workflows/release.yml)
+
 ## Getting started
@@ -12,0 +16,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

22153

increased by108.73%

Lines of code

486

increased by158.51%

Number of lines in readme file

105

increased by3.96%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes