docs(mime): update readme

jtenner · Feb 17, 2024 · e363023 · e363023
1 parent 3875d3b
commit e363023
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 21 deletions.
diff --git a/packages/mime/README.md b/packages/mime/README.md
@@ -32,6 +32,9 @@
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
+  - [Determining MIME type from file extension](#determining-mime-type-from-file-extension)
+  - [Determining file extension from MIME type](#determining-file-extension-from-mime-type)
+  - [Checking if MIME type is compressible](#checking-if-mime-type-is-compressible)
 - [Conversion from mime-db](#conversion-from-mime-db)
 - [Authors](#authors)
 - [License](#license)
@@ -40,13 +43,14 @@
 
 650+ file extension to MIME type mappings, based on mime-db.
 
-All MIME type mappings based on [mime-db](https://github.com/jshttp/mime-db)
-(2022-04-07). For filesize reasons only [a small selected
+All MIME type mappings are based on [mime-db](https://github.com/jshttp/mime-db)
+(2023-02-17). For filesize reasons only [a small selected
 number](https://github.com/thi-ng/umbrella/blob/develop/packages/mime/tools/convert.ts#L7)
-of vendor MIME types (aka `*/vnd.*`) are included. Most of the omitted ones are
-fairly obscure anyway, so likely not problematic...
+of [vendor MIME types](https://www.rfc-editor.org/rfc/rfc4288#section-3.2) (aka
+`*/vnd.*`) are included. Most of the omitted ones are fairly obscure anyway, so
+likely not problematic...
 
-Additionally, this package defines several MIME types not included in the
+Additionally, this package defines some MIME types not included in the
 original DB, as well as some preference overrides.
 
 ## Status
@@ -79,7 +83,7 @@ For Node.js REPL:
 const mime = await import("@thi.ng/mime");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.56 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.78 KB
 
 ## Dependencies
 
@@ -124,7 +128,9 @@ MIME_TYPES.jpeg
 // [ 'image/jpeg' ]
 ```
 
-To simplify lookup and support a fallback type, the package also has
+### Determining MIME type from file extension
+
+To simplify lookup and support a fallback type, the package has
 `preferredType()` function:
 
 ```ts
@@ -142,7 +148,9 @@ preferredType("foo", "text/plain")
 // "text/plain"
 ```
 
-Since v0.3.0 reverse lookups are possible too, using `preferredExtension()`
+### Determining file extension from MIME type
+
+Reverse lookups are possible too, using `preferredExtension()`
 (also supports fallback):
 
 ```ts
@@ -156,6 +164,22 @@ preferredExtension("image/foo", "dat");
 // "dat" (custom fallback)
 ```
 
+### Checking if MIME type is compressible
+
+The original [mime-db](https://github.com/jshttp/mime-db) includes information
+if a MIME type is compressible (gzippable). This information can be obtained via
+`isCompressible()`. Note: Some of these decisions seem to be questionable/wrong
+(e.g. many plain text formats are marked as false), but taken here as
+provided...
+
+```ts
+isCompressible("text/javascript");
+// true
+
+isCompressible(preferredType("mp4"))
+// false
+```
+
 ## Conversion from mime-db
 
 1. Download the [latest version of mime-db's JSON
@@ -167,11 +191,12 @@ preferredExtension("image/foo", "dat");
 
 ```bash
 # from the thi.ng/umbrella repo root
-cd packages/mime
-yarn tool:convert
+(cd packages/mime && yarn tool:convert)
 ```
 
-Additional configuration options are available in the `tools/convert.ts` script.
+Additional configuration options are available in the
+[`tools/convert.ts`](https://github.com/thi-ng/umbrella/blob/develop/packages/mime/tools/convert.ts)
+script.
 
 ## Authors
 

diff --git a/packages/mime/tpl.readme.md b/packages/mime/tpl.readme.md
@@ -6,13 +6,14 @@
 
 {{pkg.description}}
 
-All MIME type mappings based on [mime-db](https://github.com/jshttp/mime-db)
-(2022-04-07). For filesize reasons only [a small selected
+All MIME type mappings are based on [mime-db](https://github.com/jshttp/mime-db)
+(2023-02-17). For filesize reasons only [a small selected
 number](https://github.com/thi-ng/umbrella/blob/develop/packages/mime/tools/convert.ts#L7)
-of vendor MIME types (aka `*/vnd.*`) are included. Most of the omitted ones are
-fairly obscure anyway, so likely not problematic...
+of [vendor MIME types](https://www.rfc-editor.org/rfc/rfc4288#section-3.2) (aka
+`*/vnd.*`) are included. Most of the omitted ones are fairly obscure anyway, so
+likely not problematic...
 
-Additionally, this package defines several MIME types not included in the
+Additionally, this package defines some MIME types not included in the
 original DB, as well as some preference overrides.
 
 {{meta.status}}
@@ -57,7 +58,9 @@ MIME_TYPES.jpeg
 // [ 'image/jpeg' ]
 ```
 
-To simplify lookup and support a fallback type, the package also has
+### Determining MIME type from file extension
+
+To simplify lookup and support a fallback type, the package has
 `preferredType()` function:
 
 ```ts
@@ -75,7 +78,9 @@ preferredType("foo", "text/plain")
 // "text/plain"
 ```
 
-Since v0.3.0 reverse lookups are possible too, using `preferredExtension()`
+### Determining file extension from MIME type
+
+Reverse lookups are possible too, using `preferredExtension()`
 (also supports fallback):
 
 ```ts
@@ -89,6 +94,22 @@ preferredExtension("image/foo", "dat");
 // "dat" (custom fallback)
 ```
 
+### Checking if MIME type is compressible
+
+The original [mime-db](https://github.com/jshttp/mime-db) includes information
+if a MIME type is compressible (gzippable). This information can be obtained via
+`isCompressible()`. Note: Some of these decisions seem to be questionable/wrong
+(e.g. many plain text formats are marked as false), but taken here as
+provided...
+
+```ts
+isCompressible("text/javascript");
+// true
+
+isCompressible(preferredType("mp4"))
+// false
+```
+
 ## Conversion from mime-db
 
 1. Download the [latest version of mime-db's JSON
@@ -100,10 +121,11 @@ preferredExtension("image/foo", "dat");
 
 ```bash
 # from the thi.ng/umbrella repo root
-cd packages/mime
-yarn tool:convert
+(cd packages/mime && yarn tool:convert)
 ```
 
-Additional configuration options are available in the `tools/convert.ts` script.
+Additional configuration options are available in the
+[`tools/convert.ts`](https://github.com/thi-ng/umbrella/blob/develop/packages/mime/tools/convert.ts)
+script.
 
 <!-- include ../../assets/tpl/footer.md -->