Merge pull request #7 from comatory/provide-additional-options-for-constructing-urls

Provide additional options for constructing urls

Author: comatory

example/urldat_example.dart

@@ -46,4 +46,24 @@ void main() {
   assert(urldatConfig('/:id/posts/:postId',
           parameters: {'id': 10, 'postId': 200}) ==
       'https://api.example.com/v1/users/10/posts/200');
+
+  /* If you want more convenience, pass `scheme` like http/https
+     as an option.
+  */
+  assert(urldat('dart.dev', '/:section',
+          parameters: {'section': 'search'}, scheme: 'https') ==
+      'https://dart.dev/search');
+
+  /* You can also specify port for base path */
+  assert(urldat('dart.dev', '/:section',
+          parameters: {'section': 'search'}, scheme: 'https', port: 3000) ==
+      'https://dart.dev:3000/search');
+
+  /* You can also specify fragment for path */
+  assert(urldat('dart.dev', '/:section',
+          parameters: {'section': 'search'},
+          scheme: 'https',
+          port: 3000,
+          fragment: 'hello') ==
+      'https://dart.dev:3000/search#hello');
 }

lib/src/errors/errors.dart

@@ -1,14 +1,42 @@
 /// Use this to detect when [urldat.urldat] throws due to invalid
 /// combination of inputs.
+/// If you want to detect types of error programatically, use [id] property
+/// which will give you [UrldatErrorId] identifier.
 class UrldatError implements Exception {
-  UrldatError(String message) {
+  UrldatError(String message, UrldatErrorId id) {
     _message = message;
+    _id = id;
   }
+  UrldatError.basePathSchemeError()
+      : _message = 'Base path already contains a scheme. Remove scheme option.',
+        _id = UrldatErrorId.basePathSchemeError;
+  UrldatError.pathFragmentError()
+      : _message =
+            'Base path already contains a fragment. Remove fragment option.',
+        _id = UrldatErrorId.pathFragmentError;
+  UrldatError.missingParametersWithTemplateError()
+      : _message = 'When using path templates, you must pass parameters map.',
+        _id = UrldatErrorId.missingParametersWithTemplateError;
+  UrldatError.emptyParametersWithTemplateError()
+      : _message =
+            'When using path templates, you must pass non-empty parameters map.',
+        _id = UrldatErrorId.emptyParametersWithTemplateError;
 
-  String _message = '';
+  late String _message;
+  late UrldatErrorId _id;
+
+  UrldatErrorId get id => _id;
 
   @override
   String toString() {
-    return _message;
+    return [_id, _message].join('\n');
   }
 }
+
+/// ID for catching type of errors programatically
+enum UrldatErrorId {
+  basePathSchemeError,
+  pathFragmentError,
+  missingParametersWithTemplateError,
+  emptyParametersWithTemplateError,
+}

lib/src/typedefs.dart

@@ -1,10 +1,16 @@
 typedef UrldatConfiguredFn = String Function(
   String pathOrTemplate, {
   Map<String, dynamic>? parameters,
+  String? scheme,
+  int? port,
+  String? fragment,
 });
 
 typedef UrldatFn = String Function(
   String base,
   String pathOrTemplate, {
   Map<String, dynamic>? parameters,
+  String? scheme,
+  int? port,
+  String? fragment,
 });

lib/src/urldat.dart

@@ -12,27 +12,48 @@ import './errors/errors.dart';
 /// Extra keys in [parameters] that do not map to [pathOrTemplate] are
 /// always used as query parameters.
 ///
-/// If [pathOrTemplate] is template (contains `:`) and no [parameters] are
+/// If [pathOrTemplate] is template (contains `:colon`) and no [parameters] are
 /// provided, [UrldatError] exception will be thrown.
-String urldat(
-  String base,
-  String pathOrTemplate, {
-  Map<String, dynamic>? parameters,
-}) {
+///
+/// [scheme] option is a valid URI scheme. It's intended to be used
+/// with [base] URL when no scheme is present in it.
+/// Warning: Function will throw [UrldatError] when [base] path contains
+/// scheme already.
+///
+/// [port] option is a integer describing the port number, zero or 80 are
+/// ignored in the final URL
+///
+/// [fragment] option will append fragment to URL. When URL already contains
+/// fragment value, [UrldatError] will be thrown
+String urldat(String base, String pathOrTemplate,
+    {Map<String, dynamic>? parameters,
+    String? scheme,
+    int? port,
+    String? fragment}) {
+  final uri = Uri.parse(base);
+
+  if (hasScheme(uri) && scheme != null) {
+    throw UrldatError.basePathSchemeError();
+  }
+
+  if (hasFragment(pathOrTemplate) && fragment != null) {
+    throw UrldatError.pathFragmentError();
+  }
+
+  final parsedScheme = scheme != null ? Uri(scheme: scheme).scheme : null;
+
   final sanitizedBase = removeTrailingSlash(base);
   final sanitizedPathWithoutSlash =
       removeLeadingAndTrailingSlash(pathOrTemplate);
   final sanitizedPath = removeTrailingQuestionMark(sanitizedPathWithoutSlash);
 
   if (isTemplate(sanitizedPath)) {
     if (parameters == null) {
-      throw UrldatError(
-          'When using path templates, you must pass parameters map.');
+      throw UrldatError.missingParametersWithTemplateError();
     }
 
     if (parameters.isEmpty) {
-      throw UrldatError(
-          'When using path templates, you must pass non-empty parameters map.');
+      throw UrldatError.emptyParametersWithTemplateError();
     }
 
     final templateKeys = getTemplateKeys(sanitizedPath);
@@ -48,6 +69,9 @@ String urldat(
       base: sanitizedBase,
       path: filledTemplate,
       query: queryParameters,
+      scheme: parsedScheme,
+      port: port,
+      fragment: fragment,
     );
   }
 
@@ -57,5 +81,8 @@ String urldat(
     base: sanitizedBase,
     path: sanitizedPath,
     query: queryParameters,
+    scheme: parsedScheme,
+    port: port,
+    fragment: fragment,
   );
 }

lib/src/urldat_factory.dart

@@ -13,6 +13,9 @@ UrldatConfiguredFn urldatFactory(String base) {
   return (
     String pathOrTemplate, {
     Map<String, dynamic>? parameters,
+    String? scheme,
+    int? port,
+    String? fragment,
   }) =>
       urldat(base, pathOrTemplate, parameters: parameters);
 }

lib/src/utils/converters.dart

@@ -2,17 +2,26 @@ String joinParts({
   required String base,
   required String path,
   required String query,
+  String? scheme,
+  int? port,
+  String? fragment,
 }) {
+  final schemePart = scheme != null ? '$scheme://' : '';
+  final portPart = (port != null && port != 0 && port != 80) ? ':$port' : '';
+  final fragmentPart = fragment != null ? '#$fragment' : '';
+  final baseWithSchemeAndPort = '$schemePart$base$portPart';
+
   final tail = [path, query].join();
+  final tailWithFragment = '$tail$fragmentPart';
 
   /* NOTE: In case path or template is empty string, tail becomes just
            query. Do not add slash but join parts together as they are
   */
   if (tail.startsWith('?')) {
-    return [base, tail].join();
+    return [baseWithSchemeAndPort, tailWithFragment].join();
   }
 
-  return [base, tail].join('/');
+  return [baseWithSchemeAndPort, tailWithFragment].join('/');
 }
 
 Map<String, String> stringifyValuesInMap(Map<String, dynamic> map) {

lib/src/utils/detectors.dart

@@ -1,5 +1,14 @@
 final templateRegex = RegExp(r'(:{1}[^:/]+)');
+final fragmentRegex = RegExp(r'^.*\#\S*$');
 
 bool isTemplate(String path) {
   return templateRegex.hasMatch(path);
 }
+
+bool hasScheme(Uri uri) {
+  return uri.hasScheme;
+}
+
+bool hasFragment(String path) {
+  return fragmentRegex.hasMatch(path);
+}

test/urldat_test.dart

@@ -146,4 +146,45 @@ void main() {
           equals('http://localhost:3000/path/test'));
     });
   });
+
+  group('additional options', () {
+    test('should create URL with defined scheme', () {
+      expect(
+          urldat('dart.dev', '/path/:p',
+              parameters: {'p': 'test'}, scheme: 'https'),
+          equals('https://dart.dev/path/test'));
+    });
+
+    test(
+        'should throw error when scheme option is defined and'
+        'URL contains scheme as well', () {
+      expect(
+          () => urldat('https://dart.dev', '/path/:p',
+              parameters: {'p': 'test'}, scheme: 'https'),
+          throwsA(const TypeMatcher<UrldatError>()));
+    });
+
+    test('should create URL with defined port', () {
+      expect(
+          urldat('localhost', '/path/:p',
+              parameters: {'p': 'test'}, port: 4000),
+          equals('localhost:4000/path/test'));
+    });
+
+    test('should create URL with defined fragment', () {
+      expect(
+          urldat('https://dart.dev', '/path/:p',
+              parameters: {'p': 'test'}, fragment: 'about'),
+          equals('https://dart.dev/path/test#about'));
+    });
+
+    test(
+        'should throw error when fragment option is defined and'
+        'URL contains fragment as well', () {
+      expect(
+          () => urldat('https://dart.dev', '/path/:p#about',
+              parameters: {'p': 'test'}, fragment: 'about'),
+          throwsA(const TypeMatcher<UrldatError>()));
+    });
+  });
 }

test/utils/converters_test.dart

@@ -44,6 +44,86 @@ void main() {
           ),
           equals('http://example.com/path'));
     });
+
+    test('should create base with passed in scheme', () {
+      expect(
+          joinParts(
+            scheme: Uri(scheme: 'ftp').scheme,
+            base: 'example.com',
+            path: 'path',
+            query: '',
+          ),
+          equals('ftp://example.com/path'));
+    });
+
+    test('should create base with port', () {
+      expect(
+          joinParts(
+            port: 4004,
+            base: 'example.com',
+            path: 'path',
+            query: '',
+          ),
+          equals('example.com:4004/path'));
+    });
+
+    test('should ignore port 80', () {
+      expect(
+          joinParts(
+            port: 80,
+            base: 'example.com',
+            path: 'path',
+            query: '',
+          ),
+          equals('example.com/path'));
+    });
+
+    test('should ignore port 0', () {
+      expect(
+          joinParts(
+            port: 0,
+            base: 'example.com',
+            path: 'path',
+            query: '',
+          ),
+          equals('example.com/path'));
+    });
+
+    test('should create base with port and scheme and query', () {
+      expect(
+          joinParts(
+            port: 9911,
+            scheme: 'ftp',
+            base: 'example.com',
+            path: 'path',
+            query: '?search=what&category=1',
+          ),
+          equals('ftp://example.com:9911/path?search=what&category=1'));
+    });
+
+    test('should create URL with fragment', () {
+      expect(
+          joinParts(
+              base: 'example.com',
+              path: 'path/to/somewhere',
+              query: '',
+              fragment: 'about-me'),
+          equals('example.com/path/to/somewhere#about-me'));
+    });
+
+    test('should create base with port, scheme, query and fragment', () {
+      expect(
+          joinParts(
+            port: 9911,
+            scheme: 'ftp',
+            base: 'example.com',
+            path: 'path',
+            fragment: 'section-1',
+            query: '?search=what&category=1',
+          ),
+          equals(
+              'ftp://example.com:9911/path?search=what&category=1#section-1'));
+    });
   });
 
   group('stringifyValuesInMap', () {

test/utils/detectors_test.dart

@@ -12,4 +12,24 @@ void main() {
       expect(isTemplate('/path'), isFalse);
     });
   });
+
+  group('hasScheme', () {
+    test('should detect that URI has scheme', () {
+      expect(hasScheme(Uri.parse('https://dart.dev')), isTrue);
+    });
+
+    test('should NOT detect that URI has scheme', () {
+      expect(hasScheme(Uri.parse('dart.dev')), isFalse);
+    });
+  });
+
+  group('hasFragment', () {
+    test('should detect that path has fragment', () {
+      expect(hasFragment('/path/:section#fragment'), isTrue);
+    });
+
+    test('should NOT detect that path has fragment', () {
+      expect(hasFragment('/path/:section'), isFalse);
+    });
+  });
 }