Prepare 2.0.0-alpha.5. Improve JSDoc and types.

Author: Hexagon

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "proper-tags",
   "description": "A few common utility template tags for ES2015",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.5",
   "author": "Hexagon <https://github.com/hexagon>",
   "bugs": {
     "url": "http://github.com/declandewet/common-tags/issues"

package.json

@@ -4,7 +4,7 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 
 /**
  * Allows you to inline an array substitution as a comma-separated list.
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
 const commaLists = createTag(
   inlineArrayTransformer({ separator: ',' }),

src/commaLists/commaLists.js

@@ -4,7 +4,7 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 
 /**
  * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and".
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
 const commaListsAnd = createTag(
   inlineArrayTransformer({ separator: ',', conjunction: 'and' }),

src/commaListsAnd/commaListsAnd.js

@@ -4,7 +4,7 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 
 /**
  * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or".
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
 const commaListsOr = createTag(
   inlineArrayTransformer({ separator: ',', conjunction: 'or' }),

src/commaListsOr/commaListsOr.js

@@ -5,9 +5,10 @@ import { splitStringTransformer } from '../splitStringTransformer/index.js';
 import { removeNonPrintingValuesTransformer } from '../removeNonPrintingValuesTransformer/index.js';
 
 /**
- * An HTML tag function that processes a template literal and returns an HTML string.
- * @type {TemplateTag}
- */
+ * A function that returns an HTML string by processing a template literal or a JSTag function.
+ * @function
+ * @implements {TemplateTag}
+*/
 const html = createTag(
   splitStringTransformer('\n'),
   removeNonPrintingValuesTransformer(),

src/html/html.js

@@ -2,7 +2,7 @@ import { createTag } from '../createTag/index.js';
 
 /**
  * A no-op tag that might come in useful in some scenarios, e.g. mocking.
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
 const id = createTag();
 

src/id/id.js

@@ -1,13 +1,3 @@
-
-/**
- * JSTag
- * A function that takes a template literal and returns a string.
- * @typedef {function} JSTag
- * @param {TemplateStringsArray} literals - The template literal containing placeholders.
- * @param {...*} placeholders - The values to replace the placeholders in the template literal.
- * @returns {string} - The result string after processing the template literal.
- */
-
 // core
 export { createTag } from "./createTag/index.js";
 

src/index.js

@@ -2,6 +2,10 @@ import { createTag } from '../createTag/index.js';
 import { stripIndent } from '../stripIndent/index.js';
 import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a list.
+ * @implements {TemplateTag}
+ */
 const inlineLists = createTag(inlineArrayTransformer(), stripIndent);
 
 export { inlineLists };

src/inlineLists/inlineLists.js

@@ -2,6 +2,10 @@ import { createTag } from '../createTag/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 import { replaceResultTransformer } from '../replaceResultTransformer/index.js';
 
+/**
+ * Allows you to keep your single-line strings under 80 characters without resorting to crazy string concatenation.
+ * @implements {TemplateTag}
+ */
 const oneLine = createTag(
   replaceResultTransformer(/(?:\n(?:\s*))+/g, ' '),
   trimResultTransformer(),

src/oneLine/oneLine.js

@@ -3,6 +3,10 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 import { replaceResultTransformer } from '../replaceResultTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a comma-separated list, and is rendered out on to a single line.
+ * @implements {TemplateTag}
+ */
 const oneLineCommaLists = createTag(
   inlineArrayTransformer({ separator: ',' }),
   replaceResultTransformer(/(?:\s+)/g, ' '),

src/oneLineCommaLists/oneLineCommaLists.js

@@ -3,6 +3,10 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 import { replaceResultTransformer } from '../replaceResultTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and", and is rendered out on to a single line.
+ * @implements {TemplateTag}
+ */
 const oneLineCommaListsAnd = createTag(
   inlineArrayTransformer({ separator: ',', conjunction: 'and' }),
   replaceResultTransformer(/(?:\s+)/g, ' '),

src/oneLineCommaListsAnd/oneLineCommaListsAnd.js

@@ -3,6 +3,10 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 import { replaceResultTransformer } from '../replaceResultTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or", and is rendered out on to a single line.
+ * @implements {TemplateTag}
+ */
 const oneLineCommaListsOr = createTag(
   inlineArrayTransformer({ separator: ',', conjunction: 'or' }),
   replaceResultTransformer(/(?:\s+)/g, ' '),

src/oneLineCommaListsOr/oneLineCommaListsOr.js

@@ -3,6 +3,10 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 import { replaceResultTransformer } from '../replaceResultTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a list, rendered out on a single line.
+ * @implements {TemplateTag}
+ */
 const oneLineInlineLists = createTag(
   inlineArrayTransformer(),
   replaceResultTransformer(/(?:\s+)/g, ' '),

src/oneLineInlineLists/oneLineInlineLists.js

@@ -2,6 +2,10 @@ import { createTag } from '../createTag/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 import { replaceResultTransformer } from '../replaceResultTransformer/index.js';
 
+/**
+ * Allows you to keep your single-line strings under 80 characters while trimming the new lines.
+ * @implements {TemplateTag}
+ */
 const oneLineTrim = createTag(
   replaceResultTransformer(/(?:\n\s*)/g, ''),
   trimResultTransformer(),

src/oneLineTrim/oneLineTrim.js

@@ -1,3 +1,7 @@
+/**
+ * Replaces the result of all substitutions (results of calling ${ ... }) with a new value.
+ * Same as for `replaceResultTransformer`, replaceWhat can be a string or regular expression and replaceWith is the new value.
+ */
 const replaceSubstitutionTransformer = (replaceWhat, replaceWith) => {
   if (replaceWhat == null || replaceWith == null) {
     throw new Error(

src/replaceSubstitutionTransformer/replaceSubstitutionTransformer.js

@@ -4,6 +4,12 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 import { splitStringTransformer } from '../splitStringTransformer/index.js';
 import { replaceSubstitutionTransformer } from '../replaceSubstitutionTransformer/index.js';
 
+/**
+ * A tag very similar to `html` but it does safe HTML escaping for strings coming from substitutions.
+ * When combined with regular `html` tag, you can do basic HTML templating that is safe from
+ * XSS (Cross-Site Scripting) attacks.
+ * @implements {TemplateTag}
+ */
 const safeHtml = createTag(
   splitStringTransformer('\n'),
   inlineArrayTransformer(),

src/safeHtml/safeHtml.js

@@ -1,3 +1,6 @@
+/**
+ * Splits a string substitution into an array by the provided splitBy substring, only if the string contains the splitBy substring.
+ */
 const splitStringTransformer = (splitBy) => {
   if (typeof splitBy !== 'string') {
     throw new Error('You need to specify a string character to split by.');

src/splitStringTransformer/splitStringTransformer.js

@@ -2,6 +2,12 @@ import { createTag } from '../createTag/index.js';
 import { stripIndentTransformer } from '../stripIndentTransformer/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 
+/**
+ * If you want to strip the initial indentation from the beginning of each line in a multiline string.
+ * Important note: this tag will not indent multiline strings coming from the substitutions.
+ * If you want that behavior, use the `html` tag (aliases: `source`, `codeBlock`).
+ * @implements {TemplateTag}
+ */
 const stripIndent = createTag(
   stripIndentTransformer(),
   trimResultTransformer('smart'),

src/stripIndent/stripIndent.js

@@ -2,6 +2,10 @@ import { createTag } from '../createTag/index.js';
 import { stripIndentTransformer } from '../stripIndentTransformer/index.js';
 import { trimResultTransformer } from '../trimResultTransformer/index.js';
 
+/**
+ * If you want to strip *all* of the indentation from the beginning of each line in a multiline string.
+ * @implements {TemplateTag}
+ */
 const stripIndents = createTag(
   stripIndentTransformer('all'),
   trimResultTransformer('smart'),

src/stripIndents/stripIndents.js

@@ -13,25 +13,26 @@ export class TemplateTag {
     constructor(...transformers: any[]);
 }
 /**
- * An HTML tag function that processes a template literal and returns an HTML string.
- * @type {TemplateTag}
- */
-export const html: TemplateTag;
+ * A function that returns an HTML string by processing a template literal or a JSTag function.
+ * @function
+ * @implements {TemplateTag}
+*/
+export const html: Function;
 /**
  * Allows you to inline an array substitution as a comma-separated list.
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
-export const commaLists: TemplateTag;
+export const commaLists: Function;
 /**
  * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and".
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
-export const commaListsAnd: TemplateTag;
+export const commaListsAnd: Function;
 /**
  * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or".
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
-export const commaListsOr: TemplateTag;
+export const commaListsOr: Function;
 /**
  * Consumes a pipeline of composable transformer plugins and produces a template tag.
  * @param  {...Object} [...rawTransformers] - An array or arguments list of transformers
@@ -40,9 +41,9 @@ export const commaListsOr: TemplateTag;
 export function createTag(...rawTransformers: any[]): Function;
 /**
  * A no-op tag that might come in useful in some scenarios, e.g. mocking.
- * @type {TemplateTag}
+ * @implements {TemplateTag}
  */
-export const id: TemplateTag;
+export const id: Function;
 /**
  * Converts an array substitution to a string containing a list
  * @param {String} [opts.separator = '']   - The character that separates each item
@@ -52,12 +53,40 @@ export const id: TemplateTag;
  * @return {Object}                        - A transformer
  */
 export function inlineArrayTransformer({ conjunction, separator, serial, }?: string): any;
+/**
+ * Allows you to inline an array substitution as a list.
+ * @implements {TemplateTag}
+ */
 export const inlineLists: Function;
+/**
+ * Allows you to keep your single-line strings under 80 characters without resorting to crazy string concatenation.
+ * @implements {TemplateTag}
+ */
 export const oneLine: Function;
+/**
+ * Allows you to inline an array substitution as a comma-separated list, and is rendered out on to a single line.
+ * @implements {TemplateTag}
+ */
 export const oneLineCommaLists: Function;
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and", and is rendered out on to a single line.
+ * @implements {TemplateTag}
+ */
 export const oneLineCommaListsAnd: Function;
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or", and is rendered out on to a single line.
+ * @implements {TemplateTag}
+ */
 export const oneLineCommaListsOr: Function;
+/**
+ * Allows you to inline an array substitution as a list, rendered out on a single line.
+ * @implements {TemplateTag}
+ */
 export const oneLineInlineLists: Function;
+/**
+ * Allows you to keep your single-line strings under 80 characters while trimming the new lines.
+ * @implements {TemplateTag}
+ */
 export const oneLineTrim: Function;
 export function removeNonPrintingValuesTransformer(): {
     onSubstitution(substitution: any): any;
@@ -72,20 +101,43 @@ export function replaceResultTransformer(replaceWhat: (string | RegExp), replace
 export function replaceStringTransformer(replaceWhat: any, replaceWith: any): {
     onString(str: any): any;
 };
+/**
+ * Replaces the result of all substitutions (results of calling ${ ... }) with a new value.
+ * Same as for `replaceResultTransformer`, replaceWhat can be a string or regular expression and replaceWith is the new value.
+ */
 export function replaceSubstitutionTransformer(replaceWhat: any, replaceWith: any): {
     onSubstitution(substitution: any): any;
 };
+/**
+ * A tag very similar to `html` but it does safe HTML escaping for strings coming from substitutions.
+ * When combined with regular `html` tag, you can do basic HTML templating that is safe from
+ * XSS (Cross-Site Scripting) attacks.
+ * @implements {TemplateTag}
+ */
 export const safeHtml: Function;
+/**
+ * Splits a string substitution into an array by the provided splitBy substring, only if the string contains the splitBy substring.
+ */
 export function splitStringTransformer(splitBy: any): {
     onSubstitution(substitution: any): any;
 };
+/**
+ * If you want to strip the initial indentation from the beginning of each line in a multiline string.
+ * Important note: this tag will not indent multiline strings coming from the substitutions.
+ * If you want that behavior, use the `html` tag (aliases: `source`, `codeBlock`).
+ * @implements {TemplateTag}
+ */
 export const stripIndent: Function;
 /**
  * strips indentation from a template literal
  * @param  {String} type = 'initial' - whether to remove all indentation or just leading indentation. can be 'all' or 'initial'
  * @return {Object}                  - a TemplateTag transformer
  */
 export function stripIndentTransformer(type?: string): any;
+/**
+ * If you want to strip *all* of the indentation from the beginning of each line in a multiline string.
+ * @implements {TemplateTag}
+ */
 export const stripIndents: Function;
 /**
  * TemplateTag transformer that trims whitespace on the end result of a tagged template