Add If-None-Match header

Fixes #21

Author: mjackson

packages/headers/CHANGELOG.md

@@ -18,6 +18,25 @@ let cookieNames = Array.from(headers.cookie.names());
 let cookieNames = headers.cookie.names;
 ```
 
+Additionally, this release adds support for the `If-None-Match` header. This is useful for conditional GET requests where you want to return a response with content only if the ETag has changed.
+
+```ts
+import { SuperHeaders } from '@mjackson/headers';
+
+function requestHandler(request: Request): Promise<Response> {
+  let response = await callDownstreamService(request);
+
+  if (request.method === 'GET' && response.headers.has('ETag')) {
+    let headers = new SuperHeaders(request.headers);
+    if (headers.ifNoneMatch.matches(response.headers.get('ETag'))) {
+      return new Response(null, { status: 304 });
+    }
+  }
+
+  return response;
+}
+```
+
 ## v0.9.0 (2024-12-20)
 
 This release tightens up the type safety and brings `SuperHeaders` more in line with the built-in `Headers` interface.

packages/headers/README.md

@@ -100,6 +100,10 @@ headers.get('Cookie'); // 'session_id=abc123; user_id=12345; theme=dark'
 // Host
 headers.host = 'example.com';
 
+// If-None-Match
+headers.ifNoneMatch = ['67ab43', '54ed21'];
+headers.get('If-None-Match'); // '"67ab43", "54ed21"'
+
 // Last-Modified
 headers.lastModified = new Date();
 // or headers.lastModified = new Date().getTime();
@@ -366,6 +370,25 @@ let header = new Cookie([
 ]);
 ```
 
+### If-None-Match
+
+```ts
+import { IfNoneMatch } from '@mjackson/headers';
+
+let header = new IfNoneMatch('"67ab43", "54ed21"');
+
+header.has('67ab43'); // true
+header.has('21ba69'); // false
+
+header.matches('"67ab43"'); // true
+
+// Alternative init style
+let header = new IfNoneMatch(['67ab43', '54ed21']);
+let header = new IfNoneMatch({
+  tags: ['67ab43', '54ed21'],
+});
+```
+
 ### Set-Cookie
 
 ```ts

packages/headers/src/headers.ts

@@ -5,6 +5,7 @@ export { type CacheControlInit, CacheControl } from './lib/cache-control.ts';
 export { type ContentDispositionInit, ContentDisposition } from './lib/content-disposition.ts';
 export { type ContentTypeInit, ContentType } from './lib/content-type.ts';
 export { type CookieInit, Cookie } from './lib/cookie.ts';
+export { type IfNoneMatchInit, IfNoneMatch } from './lib/if-none-match.ts';
 export { type SetCookieInit, SetCookie } from './lib/set-cookie.ts';
 
 export {

packages/headers/src/lib/if-none-match.test.ts

@@ -0,0 +1,94 @@
+import * as assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { IfNoneMatch } from './if-none-match.ts';
+
+describe('IfNoneMatch', () => {
+  it('initializes with an empty string', () => {
+    let header = new IfNoneMatch('');
+    assert.deepEqual(header.tags, []);
+  });
+
+  it('initializes with a string with a single tag', () => {
+    let header = new IfNoneMatch('67ab43');
+    assert.deepEqual(header.tags, ['"67ab43"']);
+
+    let header2 = new IfNoneMatch('"67ab43"');
+    assert.deepEqual(header2.tags, ['"67ab43"']);
+
+    let header3 = new IfNoneMatch('W/"67ab43"');
+    assert.deepEqual(header3.tags, ['W/"67ab43"']);
+  });
+
+  it('initializes with a string with multiple tags', () => {
+    let header = new IfNoneMatch('67ab43, 54ed21');
+    assert.deepEqual(header.tags, ['"67ab43"', '"54ed21"']);
+
+    let header2 = new IfNoneMatch('"67ab43", "54ed21"');
+    assert.deepEqual(header2.tags, ['"67ab43"', '"54ed21"']);
+
+    let header3 = new IfNoneMatch('W/"67ab43", "54ed21"');
+    assert.deepEqual(header3.tags, ['W/"67ab43"', '"54ed21"']);
+  });
+
+  it('initializes with an array of tags', () => {
+    let header = new IfNoneMatch(['67ab43', '54ed21']);
+    assert.deepEqual(header.tags, ['"67ab43"', '"54ed21"']);
+
+    let header2 = new IfNoneMatch(['"67ab43"', '"54ed21"']);
+    assert.deepEqual(header2.tags, ['"67ab43"', '"54ed21"']);
+
+    let header3 = new IfNoneMatch(['W/"67ab43"', '"54ed21"']);
+    assert.deepEqual(header3.tags, ['W/"67ab43"', '"54ed21"']);
+  });
+
+  it('initializes with an object', () => {
+    let header = new IfNoneMatch({ tags: ['67ab43', '54ed21'] });
+    assert.deepEqual(header.tags, ['"67ab43"', '"54ed21"']);
+
+    let header2 = new IfNoneMatch({ tags: ['"67ab43"', '"54ed21"'] });
+    assert.deepEqual(header2.tags, ['"67ab43"', '"54ed21"']);
+
+    let header3 = new IfNoneMatch({ tags: ['W/"67ab43"', '"54ed21"'] });
+    assert.deepEqual(header3.tags, ['W/"67ab43"', '"54ed21"']);
+  });
+
+  it('initializes with another IfNoneMatch', () => {
+    let header = new IfNoneMatch(new IfNoneMatch('67ab43, 54ed21'));
+    assert.deepEqual(header.tags, ['"67ab43"', '"54ed21"']);
+  });
+
+  it('checks if a tag is present', () => {
+    let header = new IfNoneMatch('67ab43, 54ed21');
+    assert.ok(header.has('"67ab43"'));
+    assert.ok(header.has('"54ed21"'));
+    assert.ok(!header.has('"7892dd"'));
+    assert.ok(!header.has('*'));
+
+    let header2 = new IfNoneMatch('W/"67ab43", "54ed21"');
+    assert.ok(header2.has('W/"67ab43"'));
+    assert.ok(header2.has('"54ed21"'));
+    assert.ok(!header2.has('"7892dd"'));
+  });
+
+  it('checks if a tag matches', () => {
+    let header = new IfNoneMatch('67ab43, 54ed21');
+    assert.ok(header.matches('"67ab43"'));
+    assert.ok(header.matches('"54ed21"'));
+    assert.ok(!header.matches('"7892dd"'));
+
+    let header2 = new IfNoneMatch('W/"67ab43", "54ed21"');
+    assert.ok(header2.matches('W/"67ab43"'));
+    assert.ok(header2.matches('"54ed21"'));
+    assert.ok(!header2.matches('"7892dd"'));
+
+    let header3 = new IfNoneMatch('*');
+    assert.ok(header3.matches('"67ab43"'));
+    assert.ok(header3.matches('"54ed21"'));
+  });
+
+  it('converts to a string', () => {
+    let header = new IfNoneMatch('W/"67ab43", "54ed21"');
+    assert.equal(header.toString(), 'W/"67ab43", "54ed21"');
+  });
+});

packages/headers/src/lib/if-none-match.ts

@@ -0,0 +1,58 @@
+import { type HeaderValue } from './header-value.ts';
+import { quoteEtag } from './utils.ts';
+
+export interface IfNoneMatchInit {
+  /**
+   * The entity tags to compare against the current entity.
+   */
+  tags: string[];
+}
+
+/**
+ * The value of an `If-None-Match` HTTP header.
+ *
+ * [MDN `If-None-Match` Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match)
+ *
+ * [HTTP/1.1 Specification](https://datatracker.ietf.org/doc/html/rfc7232#section-3.2)
+ */
+export class IfNoneMatch implements HeaderValue, IfNoneMatchInit {
+  tags: string[] = [];
+
+  constructor(init?: string | string[] | IfNoneMatchInit) {
+    if (init) {
+      if (typeof init === 'string') {
+        this.tags.push(...init.split(/\s*,\s*/).map(quoteEtag));
+      } else if (Array.isArray(init)) {
+        this.tags.push(...init.map(quoteEtag));
+      } else {
+        this.tags.push(...init.tags.map(quoteEtag));
+      }
+    }
+  }
+
+  /**
+   * Checks if the header contains the given entity tag.
+   *
+   * Note: This method checks only for exact matches and does not consider wildcards.
+   *
+   * @param tag The entity tag to check for.
+   * @returns `true` if the tag is present in the header, `false` otherwise.
+   */
+  has(tag: string): boolean {
+    return this.tags.includes(quoteEtag(tag));
+  }
+
+  /**
+   * Checks if this header matches the given entity tag.
+   *
+   * @param tag The entity tag to check for.
+   * @returns `true` if the tag is present in the header (or the header contains a wildcard), `false` otherwise.
+   */
+  matches(tag: string): boolean {
+    return this.has(tag) || this.tags.includes('*');
+  }
+
+  toString() {
+    return this.tags.join(', ');
+  }
+}

packages/headers/src/lib/super-headers.test.ts

@@ -9,6 +9,7 @@ import { ContentDisposition } from './content-disposition.ts';
 import { ContentType } from './content-type.ts';
 import { Cookie } from './cookie.ts';
 import { SuperHeaders } from './super-headers.ts';
+import { IfNoneMatch } from './if-none-match.ts';
 
 describe('SuperHeaders', () => {
   it('is an instance of Headers', () => {
@@ -77,7 +78,11 @@ describe('SuperHeaders', () => {
   it('checks if a header exists', () => {
     let headers = new SuperHeaders({ 'X-Custom': 'value' });
     assert.equal(headers.has('X-Custom'), true);
-    assert.equal(headers.has('Nonexistent'), false);
+    assert.equal(headers.has('Content-Type'), false);
+
+    // Accessing this property should not change the result of has()
+    let _ = headers.contentType;
+    assert.equal(headers.has('Content-Type'), false);
   });
 
   it('iterates over entries', () => {
@@ -233,14 +238,14 @@ describe('SuperHeaders', () => {
     });
 
     it('handles the etag property', () => {
-      let headers = new SuperHeaders({ etag: '"abc"' });
-      assert.equal(headers.get('ETag'), '"abc"');
+      let headers = new SuperHeaders({ etag: '"67ab43"' });
+      assert.equal(headers.get('ETag'), '"67ab43"');
 
-      let headers2 = new SuperHeaders({ etag: 'abc' });
-      assert.equal(headers2.get('ETag'), '"abc"');
+      let headers2 = new SuperHeaders({ etag: '67ab43' });
+      assert.equal(headers2.get('ETag'), '"67ab43"');
 
-      let headers3 = new SuperHeaders({ etag: 'W/"abc"' });
-      assert.equal(headers3.get('ETag'), 'W/"abc"');
+      let headers3 = new SuperHeaders({ etag: 'W/"67ab43"' });
+      assert.equal(headers3.get('ETag'), 'W/"67ab43"');
     });
 
     it('handles the expires property', () => {
@@ -258,6 +263,11 @@ describe('SuperHeaders', () => {
       assert.equal(headers.get('If-Modified-Since'), 'Fri, 01 Jan 2021 00:00:00 GMT');
     });
 
+    it('handles the ifNoneMatch property', () => {
+      let headers = new SuperHeaders({ ifNoneMatch: ['67ab43', '54ed21'] });
+      assert.equal(headers.get('If-None-Match'), '"67ab43", "54ed21"');
+    });
+
     it('handles the ifUnmodifiedSince property', () => {
       let headers = new SuperHeaders({ ifUnmodifiedSince: new Date('2021-01-01T00:00:00Z') });
       assert.equal(headers.get('If-Unmodified-Since'), 'Fri, 01 Jan 2021 00:00:00 GMT');
@@ -542,14 +552,14 @@ describe('SuperHeaders', () => {
 
       assert.equal(headers.etag, null);
 
-      headers.etag = '"abc"';
-      assert.equal(headers.etag, '"abc"');
+      headers.etag = '"67ab43"';
+      assert.equal(headers.etag, '"67ab43"');
 
-      headers.etag = 'abc';
-      assert.equal(headers.etag, '"abc"');
+      headers.etag = '67ab43';
+      assert.equal(headers.etag, '"67ab43"');
 
-      headers.etag = 'W/"abc"';
-      assert.equal(headers.etag, 'W/"abc"');
+      headers.etag = 'W/"67ab43"';
+      assert.equal(headers.etag, 'W/"67ab43"');
 
       headers.etag = '';
       assert.equal(headers.etag, '""');
@@ -599,6 +609,25 @@ describe('SuperHeaders', () => {
       assert.equal(headers.ifModifiedSince, null);
     });
 
+    it('supports the ifNoneMatch property', () => {
+      let headers = new SuperHeaders();
+
+      assert.ok(headers.ifNoneMatch instanceof IfNoneMatch);
+
+      headers.ifNoneMatch = '"67ab43", "54ed21"';
+      assert.deepEqual(headers.ifNoneMatch.tags, ['"67ab43"', '"54ed21"']);
+
+      headers.ifNoneMatch = ['67ab43', '54ed21'];
+      assert.deepEqual(headers.ifNoneMatch.tags, ['"67ab43"', '"54ed21"']);
+
+      headers.ifNoneMatch = { tags: ['67ab43', '54ed21'] };
+      assert.deepEqual(headers.ifNoneMatch.tags, ['"67ab43"', '"54ed21"']);
+
+      headers.ifNoneMatch = null;
+      assert.ok(headers.ifNoneMatch instanceof IfNoneMatch);
+      assert.equal(headers.ifNoneMatch.toString(), '');
+    });
+
     it('supports the ifUnmodifiedSince property', () => {
       let headers = new SuperHeaders();
 

packages/headers/src/lib/super-headers.ts

@@ -7,8 +7,9 @@ import { type ContentTypeInit, ContentType } from './content-type.ts';
 import { type CookieInit, Cookie } from './cookie.ts';
 import { canonicalHeaderName } from './header-names.ts';
 import { type HeaderValue } from './header-value.ts';
+import { type IfNoneMatchInit, IfNoneMatch } from './if-none-match.ts';
 import { type SetCookieInit, SetCookie } from './set-cookie.ts';
-import { isIterable } from './utils.ts';
+import { isIterable, quoteEtag } from './utils.ts';
 
 type DateInit = number | Date;
 
@@ -85,6 +86,10 @@ interface SuperHeadersPropertyInit {
    * The [`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since) header value.
    */
   ifModifiedSince?: string | DateInit;
+  /**
+   * The [`If-None-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match) header value.
+   */
+  ifNoneMatch?: string | string[] | IfNoneMatchInit;
   /**
    * The [`If-Unmodified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Unmodified-Since) header value.
    */
@@ -131,6 +136,7 @@ const ETagKey = 'etag';
 const ExpiresKey = 'expires';
 const HostKey = 'host';
 const IfModifiedSinceKey = 'if-modified-since';
+const IfNoneMatchKey = 'if-none-match';
 const IfUnmodifiedSinceKey = 'if-unmodified-since';
 const LastModifiedKey = 'last-modified';
 const LocationKey = 'location';
@@ -251,7 +257,7 @@ export class SuperHeaders extends Headers {
    */
   has(name: string): boolean {
     let key = name.toLowerCase();
-    return key === SetCookieKey ? this.#setCookies.length > 0 : this.#map.has(key);
+    return key === SetCookieKey ? this.#setCookies.length > 0 : this.get(key) != null;
   }
 
   /**
@@ -569,10 +575,7 @@ export class SuperHeaders extends Headers {
   }
 
   set etag(value: string | undefined | null) {
-    this.#setStringValue(
-      ETagKey,
-      typeof value === 'string' && !/^(W\/)?".*"$/.test(value) ? `"${value}"` : value,
-    );
+    this.#setStringValue(ETagKey, typeof value === 'string' ? quoteEtag(value) : value);
   }
 
   /**
@@ -621,6 +624,21 @@ export class SuperHeaders extends Headers {
     this.#setDateValue(IfModifiedSinceKey, value);
   }
 
+  /**
+   * The `If-None-Match` header makes a request conditional on the absence of a matching ETag.
+   *
+   * [MDN `If-None-Match` Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match)
+   *
+   * [HTTP/1.1 Specification](https://datatracker.ietf.org/doc/html/rfc7232#section-3.2)
+   */
+  get ifNoneMatch(): IfNoneMatch {
+    return this.#getHeaderValue(IfNoneMatchKey, IfNoneMatch);
+  }
+
+  set ifNoneMatch(value: string | string[] | IfNoneMatchInit | undefined | null) {
+    this.#setHeaderValue(IfNoneMatchKey, IfNoneMatch, value);
+  }
+
   /**
    * The `If-Unmodified-Since` header makes a request conditional on the last modification date of the
    * requested resource.