@foxify/fresh
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    Fresh

    NPM Version Node Version TypeScript Version Tested With Jest Pull Requests License Build Status Coverage Status Package Quality Dependencies Status NPM Total Downloads NPM Monthly Downloads Open Issues Closed Issues Github Stars Github Forks

    HTTP response freshness testing

    Table of Contents

    Getting Started

    Prerequisites

    Installation

    npm i -s fresh

    Usage

    • TypeScript:
    import fresh from "fresh";
    • JavaScript:
    const fresh = require("fresh").default;

    Check freshness of the response using request and response headers.

    When the response is still "fresh" in the client's cache true is returned, otherwise false is returned to indicate that the client cache is now stale and the full response should be sent.

    When a client sends the Cache-Control: no-cache request header to indicate an end-to-end reload request, this module will return false to make handling these requests transparent.

    Known Issues

    This module is designed to only follow the HTTP specifications, not to work-around all kinda of client bugs (especially since this module typically does not receive enough information to understand what the client actually is).

    There is a known issue that in certain versions of Safari, Safari will incorrectly make a request that allows this module to validate freshness of the resource even when Safari does not have a representation of the resource in the cache. The module jumanji can be used in an Express application to work-around this issue and also provides links to further reading on this Safari bug.

    Example

    API usage

    const reqHeaders = { "if-none-match": '"foo"' };
    const resHeaders = { etag: '"bar"' };
    fresh(reqHeaders, resHeaders);
    // => false
     
    const reqHeaders = { "if-none-match": '"foo"' };
    const resHeaders = { etag: '"foo"' };
    fresh(reqHeaders, resHeaders);
    // => true

    Using with Node.js http server

    import fresh from "fresh";
    import http from "http";
     
    const server = http.createServer((req, res) => {
      // perform server logic
      // ... including adding ETag / Last-Modified response headers
     
      if (isFresh(req, res)) {
        // client has a fresh copy of resource
        res.statusCode = 304;
        return res.end();
      }
     
      // send the resource
      res.statusCode = 200;
      res.end("hello, world!");
    });
     
    function isFresh(req, res) {
      return fresh(req.headers, {
        etag: res.getHeader("ETag"),
        "last-modified": res.getHeader("Last-Modified"),
      });
    }
     
    server.listen(3000);

    Benchmarks

    npm run benchmarks

    Versioning

    We use SemVer for versioning. For the versions available, see the tags on this repository.

    Changelog

    See the CHANGELOG.md file for details

    Authors

    See also the list of contributors who participated in this project.

    License

    This project is licensed under the MIT License - see the LICENSE file for details

    Install

    npm i @foxify/fresh

    DownloadsWeekly Downloads

    2

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    14.6 kB

    Total Files

    8

    Last publish

    Collaborators

    • ardalanamini