Export functions based on return type (#43)

Author: fregante

index.d.ts

@@ -6,25 +6,16 @@ export interface Options {
 	*/
 	readonly attributes?: HTMLAttributes;
 
-	/**
-	The format of the generated content.
-
-	`'string'` will return it as a flat string like `'Visit <a href="https://example.com">https://example.com</a>'`.
-
-	`'dom'` will return it as a `DocumentFragment` ready to be appended in a DOM safely, like `DocumentFragment(TextNode('Visit '), HTMLAnchorElement('https://example.com'))`. This type only works in the browser.
-	*/
-	readonly type?: 'string' | 'dom';
-
 	/**
 	Set a custom HTML value for the link.
 
 	Default: The URL.
 
 	@example
 	```
-	import linkifyUrls from 'linkify-urls';
+	import {linkifyUrlsToHtml} from 'linkify-urls';
 
-	linkifyUrls('See https://sindresorhus.com/foo', {
+	linkifyUrlsToHtml('See https://sindresorhus.com/foo', {
 		value: url => new URL(url).pathname
 	});
 	//=> 'See <a href="https://sindresorhus.com/foo">/foo</a>'
@@ -34,20 +25,18 @@ export interface Options {
 
 }
 
-export interface TypeDomOptions extends Options {
-	readonly type: 'dom';
-}
-
 /**
-Linkify URLs in a string.
+Linkify URLs in a string, returns an HTML string.
 
 @param string - A string with URLs to linkify.
 
+@returns An HTML string like `'Visit <a href="https://example.com">https://example.com</a>'`.
+
 @example
 ```
-import linkifyUrls from 'linkify-urls';
+import {linkifyUrlsToHtml} from 'linkify-urls';
 
-linkifyUrls('See https://sindresorhus.com', {
+linkifyUrlsToHtml('See https://sindresorhus.com', {
 	attributes: {
 		class: 'unicorn',
 		one: 1,
@@ -56,24 +45,35 @@ linkifyUrls('See https://sindresorhus.com', {
 	}
 });
 //=> 'See <a href="https://sindresorhus.com" class="unicorn" one="1" foo multiple="a b">https://sindresorhus.com</a>'
+```
+*/
+export function linkifyUrlsToHtml(
+	string: string,
+	options?: Options
+): string;
 
-// In the browser
-const fragment = linkifyUrls('See https://sindresorhus.com', {
-	type: 'dom',
+/**
+Linkify URLs in a string, returns a `DocumentFragment`.
+
+@param string - A string with URLs to linkify.
+
+@returns a `DocumentFragment` ready to be appended in a DOM safely, like `DocumentFragment(TextNode('Visit '), HTMLAnchorElement('https://example.com'))`. This type only works in the browser.
+
+@example
+```
+import {linkifyUrlsToDom} from 'linkify-urls';
+
+const fragment = linkifyUrlsToDom('See https://sindresorhus.com', {
 	attributes: {
 		class: 'unicorn',
 	}
 });
 document.body.appendChild(fragment);
 ```
 */
-export default function linkifyUrls(
-	string: string,
-	options: TypeDomOptions
-): DocumentFragment;
-export default function linkifyUrls(
+export function linkifyUrlsToDom(
 	string: string,
 	options?: Options
-): string;
+): DocumentFragment;
 
 export {HTMLAttributes} from 'create-html-element';

index.js

@@ -4,7 +4,7 @@ import createHtmlElement from 'create-html-element';
 const urlRegex = () => (/((?<!\+)https?:\/\/(?:www\.)?(?:[-\w.]+?[.@][a-zA-Z\d]{2,}|localhost)(?:[-\w.:%+~#*$!?&/=@]*?(?:,(?!\s))*?)*)/g);
 
 // Get `<a>` element as string
-const linkify = (href, options) => createHtmlElement({
+const linkify = (href, options = {}) => createHtmlElement({
 	name: 'a',
 	attributes: {
 		href: '',
@@ -23,12 +23,16 @@ const isTruncated = (url, peek) =>
 	url.endsWith('...') // `...` is a matched by the URL regex
 	|| peek.startsWith('…'); // `…` can follow the match
 
-const getAsString = (string, options) => string.replace(urlRegex(), (url, _, offset) =>
-	(isTruncated(url, string.charAt(offset + url.length)))
-		? url // Don't linkify truncated URLs
-		: linkify(url, options));
+export function linkifyUrlsToHtml(string, options) {
+	const replacer = (url, _, offset) =>
+		isTruncated(url, string.charAt(offset + url.length))
+			? url // Don't linkify truncated URLs
+			: linkify(url, options);
 
-const getAsDocumentFragment = (string, options) => {
+	return string.replace(urlRegex(), replacer);
+}
+
+export function linkifyUrlsToDom(string, options) {
 	const fragment = document.createDocumentFragment();
 	const parts = string.split(urlRegex());
 
@@ -42,22 +46,4 @@ const getAsDocumentFragment = (string, options) => {
 	}
 
 	return fragment;
-};
-
-export default function linkifyUrls(string, options) {
-	options = {
-		attributes: {},
-		type: 'string',
-		...options,
-	};
-
-	if (options.type === 'string') {
-		return getAsString(string, options);
-	}
-
-	if (options.type === 'dom') {
-		return getAsDocumentFragment(string, options);
-	}
-
-	throw new TypeError('The type option must be either `dom` or `string`');
 }

index.test-d.ts

@@ -1,8 +1,8 @@
 import {expectType} from 'tsd';
-import linkifyUrls from './index.js';
+import {linkifyUrlsToHtml, linkifyUrlsToDom} from './index.js';
 
 expectType<string>(
-	linkifyUrls('See https://sindresorhus.com', {
+	linkifyUrlsToHtml('See https://sindresorhus.com', {
 		attributes: {
 			class: 'unicorn',
 			one: 1,
@@ -12,26 +12,23 @@ expectType<string>(
 	}),
 );
 expectType<string>(
-	linkifyUrls('See https://sindresorhus.com', {
+	linkifyUrlsToHtml('See https://sindresorhus.com', {
 		value: 'foo',
 	}),
 );
 expectType<string>(
-	linkifyUrls('See https://sindresorhus.com/foo', {
+	linkifyUrlsToHtml('See https://sindresorhus.com/foo', {
 		value: url => {
 			expectType<string>(url);
 			return url;
 		},
 	}),
 );
 expectType<string>(
-	linkifyUrls('See https://sindresorhus.com/foo', {
-		type: 'string',
-	}),
+	linkifyUrlsToHtml('See https://sindresorhus.com/foo'),
 );
 
-const fragment = linkifyUrls('See https://sindresorhus.com', {
-	type: 'dom',
+const fragment = linkifyUrlsToDom('See https://sindresorhus.com', {
 	attributes: {
 		class: 'unicorn',
 	},

readme.md

@@ -11,9 +11,9 @@ npm install linkify-urls
 ## Usage
 
 ```js
-import linkifyUrls from 'linkify-urls';
+import {linkifyUrlsToHtml, linkifyUrlsToDom} from 'linkify-urls';
 
-linkifyUrls('See https://sindresorhus.com', {
+linkifyUrlsToHtml('See https://sindresorhus.com', {
 	attributes: {
 		class: 'unicorn',
 		one: 1,
@@ -28,8 +28,7 @@ linkifyUrls('See https://sindresorhus.com', {
 
 
 // In the browser
-const fragment = linkifyUrls('See https://sindresorhus.com', {
-	type: 'dom',
+const fragment = linkifyUrlsToDom('See https://sindresorhus.com', {
 	attributes: {
 		class: 'unicorn',
 	}
@@ -39,7 +38,9 @@ document.body.appendChild(fragment);
 
 ## API
 
-### linkifyUrls(string, options?)
+### linkifyUrlsToHtml(string, options?)
+
+Returns an HTML string like `'Visit <a href="https://example.com">https://example.com</a>'`.
 
 #### string
 
@@ -57,18 +58,6 @@ Type: `object`
 
 HTML attributes to add to the link.
 
-##### type
-
-Type: `string`\
-Values: `'string' | 'dom'`\
-Default: `'string'`
-
-The format of the generated content.
-
-`'string'` will return it as a flat string like `'Visit <a href="https://example.com">https://example.com</a>'`.
-
-`'dom'` will return it as a `DocumentFragment` ready to be appended in a DOM safely, like `DocumentFragment(TextNode('Visit '), HTMLAnchorElement('https://example.com'))`. This type only works in the browser.
-
 ##### value
 
 Type: `string | Function`\
@@ -79,12 +68,22 @@ Set a custom HTML value for the link.
 If it's a function, it will receive the URL as a string:
 
 ```js
-linkifyUrls('See https://sindresorhus.com/foo', {
+linkifyUrlsToHtml('See https://sindresorhus.com/foo', {
 	value: url => new URL(url).pathname
 });
 //=> 'See <a href="https://sindresorhus.com/foo">/foo</a>'
 ```
 
+### linkifyUrlsToDom(string, options?)
+
+Returns a `DocumentFragment` ready to be appended in a DOM safely, like `DocumentFragment(TextNode('Visit '), HTMLAnchorElement('https://example.com'))`.
+
+This type only works in the browser.
+
+#### options
+
+See [options](#options) above.
+
 ## Browser compatibility
 
 Version 3 of this package uses [negative lookbehind regex syntax](https://kangax.github.io/compat-table/es2016plus/#test-RegExp_Lookbehind_Assertions). Stay on version 2 if you need to support browsers that doesn't support this feature.