BREAKING(http): rename Entity to ETagSource and calculate() to eTag()

[iuioiua]

What's changed

The Entity interface has been renamed ETagSource, and calculate() has been renamed eTag().

Why these changes were made

These changes were made to better describe the purposes of these symbols. Previously, their names were too generic for their purposes to be immediately clear.

Migration guide

To migrate, use the ETagSource interface instead of Entity and eTag() instead of calculate().

- import { calculate, type Entity } from "@std/http/etag";
+ import { eTag, type ETagSource } from "@std/http/etag";

- const body: Entity = "hello deno!";
+ const body: ETagSource = "hello deno!";

- const etag = await calculate(body);
+ const etag = await eTag(body);

  const res = new Response(body, { headers: { etag } });

Related

Closes #5141
Closes #5140

[codecov]

Codecov Report

Attention: Patch coverage is 60.00000% with 2 lines in your changes missing coverage. Please review.

Project coverage is 96.33%. Comparing base (acdea7c) to head (0b8b3ff).

Files	Patch %	Lines
http/file_server.ts	33.33%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5144   +/-   ##
=======================================
  Coverage   96.33%   96.33%           
=======================================
  Files         458      458           
  Lines       37767    37767           
  Branches     5576     5576           
=======================================
  Hits        36383    36383           
  Misses       1341     1341           
  Partials       43       43           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[timreichen]

Web APIs have the convention of using a verb first for functions. eTag() breaks that convention. Maybe it would be better to call it calculateETag() or something similar.

[kt3k]

We have many examples of functions which have the noun as its name:

• https://jsr.io/@std/media-types/doc/~/contentType
• https://jsr.io/@std/media-types/doc/~/extension
• https://jsr.io/@std/cli/doc/~/unicodeWidth
• https://jsr.io/@std/collections/doc/~/maxOf
• https://jsr.io/@std/collections/doc/~/permutations
• https://jsr.io/@std/datetime/doc/~/difference

Web APIs have the convention of using a verb first for functions. eTag() breaks that convention.

I don't think we have this convention in std.

[timreichen]

Valid point, though I think just calling it eTag() doesn't provide any information on what the function actually does except it has to do something with etag. Maybe createETag() borrowed from Deno.createKv() or toETagString() borrowed from toString() would reflect better what the function does?

[kt3k]

though I think just calling it eTag() doesn't provide any information on what the function actually does except it has to do something with etag.

It feels common to name the function as its returned thing. The above std functions are the examples of such naming convention.

I can also find many Web APIs named in that way:

• https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID
• https://developer.mozilla.org/en-US/docs/Web/API/Response/json
• https://developer.mozilla.org/en-US/docs/Web/API/Response/text
• https://developer.mozilla.org/en-US/docs/Web/API/Response/blob
• Temporal.Now.instant()
• Temporal.Now.timeZoneId()

[kt3k]

LGTM