provide better defaults for mimetype to extension mapping

CONTRIBUTING.md

@@ -31,3 +31,7 @@ All files in the project must start with the following header.
 Contributions made by corporations are covered by a different agreement than the
 one above, the
 [Software Grant and Corporate Contributor License Agreement](https://developers.google.com/open-source/cla/corporate).
+
+### Adding an extension / MIME type mapping
+If a MIME type ends up with multiple extensions, it is recommended to define a 
+preferred extension in `_preferredExtensionsMap` in [extension.dart](lib/src/extension.dart). 

README.md

@@ -57,3 +57,23 @@ request
     .map((part) => part.fold(0, (p, d) => p + d))
     .listen((length) => print('Part with length $length'));
 ```
+
+## Determining file extension by MIME type
+
+The top level function `extensionFromMime` can be used to determine the
+file extension of a given MIME type.
+
+```dart
+print(extensionFromMime('text/html'));  // Will print html
+print(extensionFromMime('image/jpeg'));  // Will print jpg
+print(extensionFromMime('application/pdf'));  // Will print pdf
+```
+
+You can override the default MIME type-extension mapping using
+`addMimeType`:
+
+```dart
+print(extensionFromMime('image/jpeg'));  // Will print jpg
+addMimeType('image/jpeg', 'jpeg');
+print(extensionFromMime('image/jpeg'));  // Will print jpeg
+```

lib/mime.dart

@@ -9,6 +9,7 @@
 /// [Internet media type](http://en.wikipedia.org/wiki/Internet_media_type).
 library mime;
 
+export 'src/extension.dart';
 export 'src/mime_multipart_transformer.dart';
 export 'src/mime_shared.dart';
 export 'src/mime_type.dart';

lib/src/extension.dart

@@ -0,0 +1,58 @@
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'default_extension_map.dart';
+
+/// Add an override for common extensions since different extensions may map
+/// to the same MIME type.
+final Map<String, String> _preferredExtensionsMap = <String, String>{
+  'application/vnd.ms-excel': 'xls',
+  'application/vnd.ms-powerpoint': 'ppt',
+  'image/jpeg': 'jpg',
+  'image/tiff': 'tif',
+  'image/svg+xml': 'svg',
+  'text/calendar': 'ics',
+  'text/javascript': 'js',
+  'text/plain': 'txt',
+  'text/sgml': 'sgml',
+  'text/x-pascal': 'pas',
+  'video/mp4': 'mp4',
+  'video/mpeg': 'mpg',
+  'video/quicktime': 'mov',
+  'video/x-matroska': 'mkv',
+};
+
+/// Lookup file extension for a given MIME type.
+///
+/// If there are multiple extensions for [mimeType], return preferred extension
+/// if defined, or the first occurrence in the map.
+/// If no extension is found, `null` is returned.
+String? extensionFromMimeOrNull(String mimeType) {
+  final mimeTypeLC = mimeType.toLowerCase();
+  if (_preferredExtensionsMap.containsKey(mimeTypeLC)) {
+    return _preferredExtensionsMap[mimeTypeLC]!;
+  }
+  return defaultExtensionMap.entries
+      .firstWhereOrNull((entry) => entry.value == mimeTypeLC)
+      ?.key;
+}
+
+String extensionFromMime(String mimeType, {String? orElse}) =>
+    extensionFromMimeOrNull(mimeType) ?? orElse ?? mimeType;
+
+/// Allow for a user-specified MIME type-extension mapping that overrides the
+/// default.
+void addMimeType(String mimeType, String extension) {
+  _preferredExtensionsMap[mimeType.toLowerCase()] = extension.toLowerCase();
+}
+
+extension _IterableExtension<T> on Iterable<T> {
+  /// The first element satisfying [test], or `null` if there are none.
+  T? firstWhereOrNull(bool Function(T element) test) {
+    for (var element in this) {
+      if (test(element)) return element;
+    }
+    return null;
+  }
+}

lib/src/mime_type.dart

@@ -23,20 +23,6 @@ int get defaultMagicNumbersMaxLength => _globalResolver.magicNumbersMaxLength;
 String? lookupMimeType(String path, {List<int>? headerBytes}) =>
     _globalResolver.lookup(path, headerBytes: headerBytes);
 
-/// Returns the extension for the given MIME type.
-///
-/// If there are multiple extensions for [mime], return the first occurrence in
-/// the map. If there are no extensions for [mime], return [mime].
-String extensionFromMime(String mime) {
-  mime = mime.toLowerCase();
-  for (final entry in defaultExtensionMap.entries) {
-    if (defaultExtensionMap[entry.key] == mime) {
-      return entry.key;
-    }
-  }
-  return mime;
-}
-
 /// MIME-type resolver class, used to customize the lookup of mime-types.
 class MimeTypeResolver {
   final Map<String, String> _extensionMap = {};

test/extension_test.dart

@@ -0,0 +1,63 @@
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:mime/mime.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('global-lookup-mime-type', () {
+    test('valid-mime-type', () {
+      expect(extensionFromMime('text/x-dart'), equals('dart'));
+      expect(extensionFromMime('text/javascript'), equals('js'));
+      expect(extensionFromMime('application/java-archive'), equals('jar'));
+      expect(extensionFromMime('application/json'), equals('json'));
+      expect(extensionFromMime('application/pdf'), equals('pdf'));
+      expect(extensionFromMime('application/vnd.ms-excel'), equals('xls'));
+      expect(extensionFromMime('application/xhtml+xml'), equals('xht'));
+      expect(extensionFromMime('image/jpeg'), equals('jpg'));
+      expect(extensionFromMime('image/png'), equals('png'));
+      expect(extensionFromMime('text/css'), equals('css'));
+      expect(extensionFromMime('text/html'), equals('htm'));
+      expect(extensionFromMime('text/plain'), equals('txt'));
+      expect(extensionFromMime('text/x-c'), equals('c'));
+    });
+
+    test('invalid-mime-type', () {
+      expect(extensionFromMime('invalid-mime-type'), 'invalid-mime-type');
+      expect(extensionFromMime('invalid/mime/type'), 'invalid/mime/type');
+
+      expect(
+          extensionFromMime('invalid-mime-type', orElse: 'invalid'), 'invalid');
+      expect(
+          extensionFromMime('invalid/mime/type', orElse: 'invalid'), 'invalid');
+
+      expect(extensionFromMimeOrNull('invalid-mime-type'), isNull);
+      expect(extensionFromMimeOrNull('invalid/mime/type'), isNull);
+    });
+
+    test('unknown-mime-type', () {
+      expect(extensionFromMime('application/to-be-invented'),
+          'application/to-be-invented');
+
+      expect(extensionFromMime('application/to-be-invented', orElse: 'unknown'),
+          'unknown');
+
+      expect(extensionFromMimeOrNull('application/to-be-invented'), isNull);
+    });
+  });
+
+  group('add-mime-type', () {
+    test('new-mime-type', () {
+      expect(extensionFromMimeOrNull('custom/type'), isNull);
+      addMimeType('custom/type', 'ct');
+      expect(extensionFromMime('custom/type'), equals('ct'));
+    });
+
+    test('overridden-mime-type', () {
+      expect(extensionFromMime('image/jpeg'), equals('jpg'));
+      addMimeType('image/jpeg', 'jpeg');
+      expect(extensionFromMime('image/jpeg'), equals('jpeg'));
+    });
+  });
+}

test/mime_type_test.dart

@@ -184,21 +184,4 @@ void main() {
     expect(initialMagicNumbersMaxLength, actualMaxBytes);
   });
 
-  group('extensionFromMime', () {
-    test('returns match for mime with single extension', () {
-      expect(extensionFromMime('application/json'), equals('json'));
-      expect(extensionFromMime('application/java-archive'), equals('jar'));
-    });
-
-    test('returns first match for mime with multiple extensions', () {
-      expect(extensionFromMime('text/html'), equals('htm'));
-      expect(extensionFromMime('application/x-cbr'), equals('cb7'));
-    });
-
-    test('returns inputted string for unrecognized mime', () {
-      expect(
-          extensionFromMime('unrecognized_mime'), equals('unrecognized_mime'));
-      expect(extensionFromMime('i/am/not/a/mime'), equals('i/am/not/a/mime'));
-    });
-  });
 }