feat: add media_types

media_types/README.md

@@ -0,0 +1,127 @@
+# std/media_types
+
+Provides an API for handling media (MIME) types.
+
+These APIs are inspired by the GoLang [`mime`](https://pkg.go.dev/mime) package
+and [jshttp/mime-types](https://github.com/jshttp/mime-types), and is designed
+to integrate and improve the APIs from
+[deno.land/x/media_types](https://deno.land/x/media_types).
+
+The `vendor` folder contains copy of the
+[jshttp/mime-db](https://github.com/jshttp/mime-types) `db.json` file along with
+its license.
+
+## `contentType()`
+
+Given a extension or media type, return a fully qualified header value for
+setting a `Content-Type` or `Content-Disposition` header. The function will
+process the value passed as a media type if it contains a `/`, otherwise will
+attempt to match as an extension, with or without the leading `.`.
+
+> Note: a side effect of `deno/x/media_types` was that you could pass a file
+> name (e.g. `file.json`) and it would return the content type. This behavior is
+> intentionally not supported here. If you want to get an extension for a file
+> name, use `extname()` from `std/path/mod.ts` to determine the extension and
+> pass it here.
+
+```ts
+import { contentType } from "https://deno.land/std@$STD_VERSION/media_types/mod.ts";
+
+contentType(".json"); // `application/json; charset=UTF-8`
+contentType("text/html"); // `text/html; charset=UTF-8`
+contentType("txt"); // `text/plain; charset=UTF-8`
+contentType("foo"); // undefined
+contentType("file.json"); // undefined
+```
+
+## `extension()`
+
+Given a media type, return the most relevant extension. If no extension can be
+determined `undefined` is returned.
+
+```ts
+import { extension } from "https://deno.land/std@$STD_VERSION/media_types/mod.ts";
+
+extension("text/plain"); // `txt`
+extension("application/json"); // `json`
+extension("text/html; charset=UTF-8"); // `html`
+extension("application/foo"); // undefined
+```
+
+## `extensionsByType()`
+
+Given a media type, return an array of extensions that can be applied. If no
+extension can be determined `undefined` is returned.
+
+```ts
+import { extensionsByType } from "https://deno.land/std@$STD_VERSION/media_types/mod.ts";
+
+extensionsByType("application/json"); // ["js", "mjs"]
+extensionsByType("text/html; charset=UTF-8"); // ["html", "htm", "shtml"]
+extensionsByType("application/foo"); // undefined
+```
+
+## `formatMediaType()`
+
+Given a media type and optional parameters, return a spec compliant value. If
+the parameters result in a non-compliant value, an empty string (`""`) is
+returned.
+
+```ts
+import { formatMediaType } from "https://deno.land/std@$STD_VERSION/media_types/mod.ts";
+
+formatMediaType("text/plain", { charset: "UTF-8" }); // `text/plain; charset=UTF-8`
+```
+
+## `getCharset()`
+
+Given a media type, return the charset encoding for the value.
+
+```ts
+import { getCharset } from "https://deno.land/std@$STD_VERSION/media_types/mod.ts";
+
+getCharset("text/plain"); // `UTF-8`
+getCharset("application/foo"); // undefined
+getCharset("application/news-checkgroups"); // `US-ASCII`
+getCharset("application/news-checkgroups; charset=UTF-8"); // `UTF-8`
+```
+
+## `parseMediaType()`
+
+Given a header value string, parse a value into a media type and any optional
+parameters. If the supplied value is invalid, the function will throw.
+
+```ts
+import { parseMediaType } from "https://deno.land/std@$STD_VERSION/media_types/mod.ts";
+import { assertEquals } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+
+assertEquals(
+  parseMediaType("application/JSON"),
+  [
+    "application/json",
+    undefined,
+  ],
+);
+
+assertEquals(
+  parseMediaType("text/html; charset=UTF-8"),
+  [
+    "application/json",
+    { charset: "UTF-8" },
+  ],
+);
+```
+
+## `typeByExtension()`
+
+Given an extension, return a media type. The extension can have a leading `.` or
+not.
+
+```ts
+import { typeByExtension } from "https://deno.land/std@$STD_VERSION/media_types/mod.ts";
+
+typeByExtension("js"); // `application/json`
+typeByExtension(".HTML"); // `text/html`
+typeByExtension("foo"); // undefined
+typeByExtension("file.json"); // undefined
+```

media_types/_util.ts

@@ -0,0 +1,143 @@
+// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+
+/** Supporting functions for media_types that do not make part of the public
+ * API.
+ *
+ * @module
+ * @private
+ */
+
+export function consumeToken(v: string): [token: string, rest: string] {
+  const notPos = indexOf(v, isNotTokenChar);
+  if (notPos == -1) {
+    return [v, ""];
+  }
+  if (notPos == 0) {
+    return ["", v];
+  }
+  return [v.slice(0, notPos), v.slice(notPos)];
+}
+
+export function consumeValue(v: string): [value: string, rest: string] {
+  if (!v) {
+    return ["", v];
+  }
+  if (v[0] !== `"`) {
+    return consumeToken(v);
+  }
+  let value = "";
+  for (let i = 1; i < v.length; i++) {
+    const r = v[i];
+    if (r === `"`) {
+      return [value, v.slice(i + 1)];
+    }
+    if (r === "\\" && i + 1 < v.length && isTSpecial(v[i + 1])) {
+      value += v[i + 1];
+      i++;
+      continue;
+    }
+    if (r === "\r" || r === "\n") {
+      return ["", v];
+    }
+    value += v[i];
+  }
+  return ["", v];
+}
+
+export function consumeMediaParam(
+  v: string,
+): [key: string, value: string, rest: string] {
+  let rest = v.trimStart();
+  if (!rest.startsWith(";")) {
+    return ["", "", v];
+  }
+  rest = rest.slice(1);
+  rest = rest.trimStart();
+  let param: string;
+  [param, rest] = consumeToken(rest);
+  param = param.toLowerCase();
+  if (!param) {
+    return ["", "", v];
+  }
+  rest = rest.slice(1);
+  rest = rest.trimStart();
+  const [value, rest2] = consumeValue(rest);
+  if (value == "" && rest2 === rest) {
+    return ["", "", v];
+  }
+  rest = rest2;
+  return [param, value, rest];
+}
+
+export function decode2331Encoding(v: string): string | undefined {
+  const sv = v.split(`'`, 3);
+  if (sv.length !== 3) {
+    return undefined;
+  }
+  const charset = sv[0].toLowerCase();
+  if (!charset) {
+    return undefined;
+  }
+  if (charset != "us-ascii" && charset != "utf-8") {
+    return undefined;
+  }
+  const encv = decodeURI(sv[2]);
+  if (!encv) {
+    return undefined;
+  }
+  return encv;
+}
+
+function indexOf<T>(s: Iterable<T>, fn: (s: T) => boolean): number {
+  let i = -1;
+  for (const v of s) {
+    i++;
+    if (fn(v)) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+export function isIterator<T>(obj: unknown): obj is Iterable<T> {
+  if (obj == null) {
+    return false;
+  }
+  // deno-lint-ignore no-explicit-any
+  return typeof (obj as any)[Symbol.iterator] === "function";
+}
+
+export function isToken(s: string): boolean {
+  if (!s) {
+    return false;
+  }
+  return indexOf(s, isNotTokenChar) < 0;
+}
+
+function isNotTokenChar(r: string): boolean {
+  return !isTokenChar(r);
+}
+
+function isTokenChar(r: string): boolean {
+  const code = r.charCodeAt(0);
+  return code > 0x20 && code < 0x7f && !isTSpecial(r);
+}
+
+function isTSpecial(r: string): boolean {
+  return `()<>@,;:\\"/[]?=`.includes(r[0]);
+}
+
+const CHAR_CODE_SPACE = " ".charCodeAt(0);
+const CHAR_CODE_TILDE = "~".charCodeAt(0);
+
+export function needsEncoding(s: string): boolean {
+  for (const b of s) {
+    const charCode = b.charCodeAt(0);
+    if (
+      (charCode < CHAR_CODE_SPACE || charCode > CHAR_CODE_TILDE) && b !== "\t"
+    ) {
+      return true;
+    }
+  }
+  return false;
+}

media_types/_util_test.ts

@@ -0,0 +1,67 @@
+// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+
+import { assertEquals } from "../testing/asserts.ts";
+import { consumeMediaParam, consumeToken, consumeValue } from "./_util.ts";
+
+Deno.test({
+  name: "media_types::util - consumeToken()",
+  fn() {
+    const fixtures = [
+      ["foo bar", "foo", " bar"],
+      ["bar", "bar", ""],
+      ["", "", ""],
+      [" foo", "", " foo"],
+    ] as const;
+    for (const [fixture, token, rest] of fixtures) {
+      assertEquals(consumeToken(fixture), [token, rest]);
+    }
+  },
+});
+
+Deno.test({
+  name: "media_types::util - consumeValue()",
+  fn() {
+    const fixtures = [
+      ["foo bar", "foo", " bar"],
+      ["bar", "bar", ""],
+      [" bar ", "", " bar "],
+      [`"My value"end`, "My value", "end"],
+      [`"My value" end`, "My value", " end"],
+      [`"\\\\" rest`, "\\", " rest"],
+      [`"My \\" value"end`, 'My " value', "end"],
+      [`"\\" rest`, "", `"\\" rest`],
+      [`"C:\\dev\\go\\robots.txt"`, `C:\\dev\\go\\robots.txt`, ""],
+      [`"C:\\新建文件夹\\中文第二次测试.mp4"`, `C:\\新建文件夹\\中文第二次测试.mp4`, ""],
+    ] as const;
+    for (const [fixture, value, rest] of fixtures) {
+      assertEquals(consumeValue(fixture), [value, rest]);
+    }
+  },
+});
+
+Deno.test({
+  name: "media_types::util - consumeMediaParam()",
+  fn() {
+    const fixtures = [
+      [" ; foo=bar", "foo", "bar", ""],
+      ["; foo=bar", "foo", "bar", ""],
+      [";foo=bar", "foo", "bar", ""],
+      [";FOO=bar", "foo", "bar", ""],
+      [`;foo="bar"`, "foo", "bar", ""],
+      [`;foo="bar"; `, "foo", "bar", "; "],
+      [`;foo="bar"; foo=baz`, "foo", "bar", "; foo=baz"],
+      [` ; boundary=----CUT;`, "boundary", "----CUT", ";"],
+      [
+        ` ; key=value;  blah="value";name="foo" `,
+        "key",
+        "value",
+        `;  blah="value";name="foo" `,
+      ],
+      [`;  blah="value";name="foo" `, "blah", "value", `;name="foo" `],
+      [`;name="foo" `, "name", "foo", ` `],
+    ] as const;
+    for (const [fixture, key, value, rest] of fixtures) {
+      assertEquals(consumeMediaParam(fixture), [key, value, rest]);
+    }
+  },
+});