From 18ae9342903ad62b48844f9c52a0076d4f052faf Mon Sep 17 00:00:00 2001 From: Robert Kieffer Date: Wed, 16 Aug 2017 16:02:04 -0700 Subject: [PATCH] README --- README.md | 40 +++++++++++++++++++++------------------- src/README_js.md | 40 +++++++++++++++++++++------------------- 2 files changed, 42 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 5dc82e3c..e8fda859 100644 --- a/README.md +++ b/README.md @@ -19,16 +19,20 @@ mime.getExtension('text/plain'); // ⇨ 'txt' ``` -## Lite and Browser-Ready Versions +See [Mime API](#mime-api) below for API details. -There is also a "lite" version of this module that omits the ~600 -vendor-specific (`*/vnd.*`) and experimental (`*/x-*`) types, available as -follows: +## Lite Version + +There is also a "lite" version of this module that omits vendor-specific +(`*/vnd.*`) and experimental (`*/x-*`) types. It weighs in at ~2.5KB, compared +to 8KB for the full version. To load the lite version: ```javascript const mime = require('mime/lite'); ``` +## Browser-ready Versions + To use this module in the browser, you would typlically use [webpack](https://webpack.github.io/) or [browserify](http://browserify.org/) to package your code. However, browser-ready versions are available via wzrd.in. @@ -50,26 +54,24 @@ mime.getType(...); // etc. ## Mime .vs. mime-types .vs. mime-db modules -For those of you wondering about the difference between these NPM modules, +For those of you wondering about the difference between these [popular] NPM modules, here's a brief rundown ... -The [`mime-db`](https://github.com/jshttp/mime-db) module is "the source of -truth" for MIME type information. It is not an API, just a dataset that -incorporates MIME type definitions from IANA, Apache, NGINX, and custom mappings -submitted by the community. +[`mime-db`](https://github.com/jshttp/mime-db) is "the source of +truth" for MIME type information. It is not an API. Rather, it is a canonical +dataset of mime type definitions pulled from IANA, Apache, NGINX, and custom mappings +submitted by the Node.js community. -The [`mime-types`](https://github.com/jshttp/mime-types) module is a thin -wrapper around mime-db that provides an API similar to the version 1 `mime` API. +[`mime-types`](https://github.com/jshttp/mime-types) is a thin +wrapper around mime-db that provides an API drop-in compatible(ish) with `mime @ < v1.3.6` API. -This module, `mime`, as of version 2, is a self-contained module that provides -an optimized version of `mime-db` and a simplified API, with the following -characteristics: +`mime` is, as of v2, a self-contained module bundled with a pre-optimized version +of the `mime-db` dataset. It provides a simplified API with the following characteristics: * Internally consistent type ⇔ extension mapping. I.e. `mime.getType(mime.getExtension(type)) == type` will always be true -* API method naming consistent with industry best-practices -* Compact footprint. Minified + gzip sizes of the various modules are as -follows: +* Method naming consistent with industry best-practices +* Compact footprint. E.g. The minified+compressed sizes of the various modules: Module | Size --- | --- @@ -145,13 +147,13 @@ mime.getExtension('text/html; charset=utf8'); // ⇨ 'html' ### mime.define(typeMap[, force = false]) -Apply type mappings. +Define [more] type mappings. `typeMap` is a map of type -> extensions, as documented in `new Mime`, above. By default this method will throw an error if you try to map a type to an extension that is already assigned to another type. Passing `true` for the -`force` argument will suppress this behavior and apply the new mapping. +`force` argument will suppress this behavior (overriding any previous mapping). ```javascript mime.define({'text/x-abc': ['abc', 'abcd']}); diff --git a/src/README_js.md b/src/README_js.md index 60be4d15..775a653d 100644 --- a/src/README_js.md +++ b/src/README_js.md @@ -21,16 +21,20 @@ mime.getType('txt'); // RESULT mime.getExtension('text/plain'); // RESULT ``` -## Lite and Browser-Ready Versions +See [Mime API](#mime-api) below for API details. -There is also a "lite" version of this module that omits the ~600 -vendor-specific (`*/vnd.*`) and experimental (`*/x-*`) types, available as -follows: +## Lite Version + +There is also a "lite" version of this module that omits vendor-specific +(`*/vnd.*`) and experimental (`*/x-*`) types. It weighs in at ~2.5KB, compared +to 8KB for the full version. To load the lite version: ```javascript const mime = require('mime/lite'); ``` +## Browser-ready Versions + To use this module in the browser, you would typlically use [webpack](https://webpack.github.io/) or [browserify](http://browserify.org/) to package your code. However, browser-ready versions are available via wzrd.in. @@ -52,26 +56,24 @@ mime.getType(...); // etc. ## Mime .vs. mime-types .vs. mime-db modules -For those of you wondering about the difference between these NPM modules, +For those of you wondering about the difference between these [popular] NPM modules, here's a brief rundown ... -The [`mime-db`](https://github.com/jshttp/mime-db) module is "the source of -truth" for MIME type information. It is not an API, just a dataset that -incorporates MIME type definitions from IANA, Apache, NGINX, and custom mappings -submitted by the community. +[`mime-db`](https://github.com/jshttp/mime-db) is "the source of +truth" for MIME type information. It is not an API. Rather, it is a canonical +dataset of mime type definitions pulled from IANA, Apache, NGINX, and custom mappings +submitted by the Node.js community. -The [`mime-types`](https://github.com/jshttp/mime-types) module is a thin -wrapper around mime-db that provides an API similar to the version 1 `mime` API. +[`mime-types`](https://github.com/jshttp/mime-types) is a thin +wrapper around mime-db that provides an API drop-in compatible(ish) with `mime @ < v1.3.6` API. -This module, `mime`, as of version 2, is a self-contained module that provides -an optimized version of `mime-db` and a simplified API, with the following -characteristics: +`mime` is, as of v2, a self-contained module bundled with a pre-optimized version +of the `mime-db` dataset. It provides a simplified API with the following characteristics: * Internally consistent type ⇔ extension mapping. I.e. `mime.getType(mime.getExtension(type)) == type` will always be true -* API method naming consistent with industry best-practices -* Compact footprint. Minified + gzip sizes of the various modules are as -follows: +* Method naming consistent with industry best-practices +* Compact footprint. E.g. The minified+compressed sizes of the various modules: Module | Size --- | --- @@ -143,13 +145,13 @@ mime.getExtension('text/html; charset=utf8'); // RESULT ### mime.define(typeMap[, force = false]) -Apply type mappings. +Define [more] type mappings. `typeMap` is a map of type -> extensions, as documented in `new Mime`, above. By default this method will throw an error if you try to map a type to an extension that is already assigned to another type. Passing `true` for the -`force` argument will suppress this behavior and apply the new mapping. +`force` argument will suppress this behavior (overriding any previous mapping). ```javascript --context mime.define({'text/x-abc': ['abc', 'abcd']});