littoral-templates 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 0.5.1
+
+* Package `src/` for debuggability.
+
+
 ## 0.5.0
 
 * Separated out `setEOLStyleFromOS` to a separate package `littoral-templates-node`.

package/dist/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAM,QAAQ,EAAC,MAAM,qBAAqB,CAAA;AAIjD;;;GAGG;AACH,eAAO,MAAM,SAAS,aAAc,QAAQ,KAAG,MAAM,EAQpD,CAAA;AAGD;;GAEG;AACH,eAAO,MAAM,QAAQ,aAAc,QAAQ,KAAG,MACY,CAAA"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAM,QAAQ,EAAC,MAAM,qBAAqB,CAAA;AAIjD;;;GAGG;AACH,eAAO,MAAM,SAAS,aAAc,QAAQ,KAAG,MAAM,EAUpD,CAAA;AAGD;;GAEG;AACH,eAAO,MAAM,QAAQ,aAAc,QAAQ,KAAG,MACY,CAAA"}

package/dist/primitives.js

@@ -17,6 +17,9 @@ var eolRegex = new RegExp(/\r*\n/);
  * Note: doesn't need to be exposed.
  */
 export var flattened = function (template) {
+    if (template === undefined || template === null) {
+        return [];
+    }
     if (typeof template === "function") {
         return flattened(template());
     }

package/dist/primitives.js.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA;;GAEG;;;;;;;;;;AAEH,OAAO,EAAC,GAAG,EAAW,MAAM,qBAAqB,CAAA;AAEjD,IAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAA;AAEpC;;;GAGG;AACH,MAAM,CAAC,IAAM,SAAS,GAAG,UAAC,QAAkB;IACxC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAA;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,UAAC,IAAI,EAAE,IAAI,IAAK,uCAAI,IAAI,SAAK,IAAI,SAAjB,CAAkB,EAAE,EAAE,CAAC,CAAA;IACjF,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;AACnC,CAAC,CAAA;AAGD;;GAEG;AACH,MAAM,CAAC,IAAM,QAAQ,GAAG,UAAC,QAAkB;IACvC,OAAA,SAAS,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,UAAC,IAAI,IAAK,OAAA,IAAI,GAAG,GAAG,EAAV,CAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AAAtD,CAAsD,CAAA"}
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA;;GAEG;;;;;;;;;;AAEH,OAAO,EAAC,GAAG,EAAW,MAAM,qBAAqB,CAAA;AAEjD,IAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAA;AAEpC;;;GAGG;AACH,MAAM,CAAC,IAAM,SAAS,GAAG,UAAC,QAAkB;IACxC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAA;IACb,CAAC;IAAI,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACtC,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAA;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,UAAC,IAAI,EAAE,IAAI,IAAK,uCAAI,IAAI,SAAK,IAAI,SAAjB,CAAkB,EAAE,EAAE,CAAC,CAAA;IACjF,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;AACnC,CAAC,CAAA;AAGD;;GAEG;AACH,MAAM,CAAC,IAAM,QAAQ,GAAG,UAAC,QAAkB;IACvC,OAAA,SAAS,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,UAAC,IAAI,IAAK,OAAA,IAAI,GAAG,GAAG,EAAV,CAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AAAtD,CAAsD,CAAA"}

package/dist/types.d.ts

@@ -7,7 +7,7 @@
  *
  * @since version 0.3.0
  */
-export type Template = string | (() => Template) | Array<Template>;
+export type Template = string | undefined | null | Array<Template> | (() => Template);
 /**
  * Legacy alias for the {@link Template} type definition.
  * Note: this type might be deprecated and removed (per a major version) in the future.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAA;AAElE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,QAAQ,CAAC,CAAA;AAErF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "littoral-templates",
-    "version": "0.5.0",
+    "version": "0.5.1",
     "description": "A small JavaScript/TypeScript framework to do templating comfortably using the template literal syntax in either JavaScript or TypeScript",
     "license": "MIT",
     "author": "Meinte Boersma",

package/src/eol.ts

@@ -0,0 +1,37 @@
+/**
+ * EOL-related constants and functions.
+ */
+
+/**
+ * Common EOL styles.
+ */
+export const eolStyles = {
+    lf: "\n",
+    crlf: "\r\n"
+} as const
+
+
+/**
+ * The value of the EOL string: typically, either "\n" (=LF-style, compatible with POSIX/Linux/macOS), or "\r\n" (=CRLF-style, compatible with Windows).
+ */
+export let eol: string = eolStyles.lf
+
+
+/**
+ * Sets the EOL explicitly to the given value.
+ * (This is especially useful for testing.)
+ */
+export const setEOLExplicitly = (newEol: string) => {
+    eol = newEol
+}
+
+
+const splitRegex = new RegExp(/\r*\n/)
+
+/**
+ * Splits the given string on EOLs (of any style) into an array of strings,
+ * each corresponding to one line.
+ */
+export const splitOnEOL = (str: string): string[] =>
+    str.split(splitRegex)
+

package/src/functions.ts

@@ -0,0 +1,50 @@
+/**
+ * Non-primitive functions on the {@link Template} type.
+ */
+
+import {flattened, Template} from "./index-internal.js"
+
+/**
+ * Allows for the following syntax:
+ * <pre>
+ * [
+ *     when(<some boolean condition>)(
+ *      <stuff to include when boolean condition is true>
+ *     )
+ * ]
+ * </pre>
+ *
+ * and
+ *
+ * <pre>
+ * [
+ *     when(<some boolean condition>)(
+ *      () => <stuff to include when boolean condition is true>
+ *     )
+ * ]
+ * </pre>
+ *
+ * In the latter case, it's guaranteed that the thunk ({@see https://en.wikipedia.org/wiki/Thunk})
+ * is only evaluated (/run) when the boolean condition is true.
+ * That is useful in case the stuff to include produces side effects.
+ *
+ * Note that the second Curried argument is variadic, so it doesn't require array brackets (`[]`).
+ */
+export const when = (bool: boolean): ((...whenResults: Template[]) => Template) =>
+    bool
+        ? (...whenResults: Template[]) => flattened(whenResults)  // (need to be explicit here, or it doesn't work – despite having specified the return type...)
+        : (_) => []
+
+
+/**
+ * @return a function that composes the given template function with the action of "adding an empty line after".
+ */
+export const withEmptyLineAppended = <T>(templateFunc: (t: T) => Template) =>
+    (t: T) => [templateFunc(t), ``]
+
+/**
+ * A legacy alias of {@link withEmptyLineAppended}.
+ * Note: this function might be deprecated and removed (per a major version) in the future.
+ */
+export const withNewlineAppended = withEmptyLineAppended
+

package/src/indents.ts

@@ -0,0 +1,47 @@
+/**
+ * Indentation-related constants and functions.
+ */
+
+import {flattened, repeat, Template} from "./index-internal.js"
+
+/**
+ * @returns a function to instantiate a function to indent a sub-template.
+ * The function always returns an array of strings.
+ *
+ * Its usage looks as follows:
+ * <pre>
+ * indentWith("  ")(2)([
+ *     `this is indented 2 levels`
+ * ])
+ * </pre>
+ * Note that the third Curried argument is variadic, so the array brackets (`[]`) can be elided.
+ *
+ * Usually, one sets up the following function constant before:
+ * <pre>
+ * const indent = indentWith("  ")
+ * </pre>
+ */
+export const indentWith = (singleIndentation: string) =>
+    (indentLevel: number = 1) => {
+        const prefix = repeat(singleIndentation, indentLevel)
+        const indenter = (line: string) => line.length > 0 ? (prefix + line) : line
+        return (...templates: Template[]) =>
+            flattened(templates).map(indenter)    // Note: Template[] has type Template as well!
+    }
+
+/**
+ * An enumeration of common indentation styles.
+ * Use these in a type-safe way as follows, e.g. for “1 tab”:
+ *
+ * ```
+ * const indent = indentWith(commonIndentations["1 tab"])
+ *
+ * indent([`foo`])
+ * ```
+ */
+export const commonIndentations = {
+    "2 spaces": "  ",
+    "4 spaces": "    ",
+    "1 tab": "\t"
+} as const
+

package/src/index-internal.ts

@@ -0,0 +1,16 @@
+export * from "./eol.js"
+export * from "./functions.js"
+export * from "./indents.js"
+export * from "./primitives.js"
+export * from "./strings.js"
+export * from "./types.js"
+
+/**
+ * To avoid problems with circular dependencies between JavaScript – i.e.: transpiled TypeScript – files,
+ * members in any .ts file *must* be imported through this index-internal.ts, e.g.:
+ *
+ * `import {asString} from "./index-internal.js"`
+ *
+ * (Mind the .js extension!)
+ */
+

package/src/index.ts

@@ -0,0 +1,15 @@
+export {
+    asString,
+    commaSeparated,
+    commonIndentations,
+    indentWith,
+    setEOLExplicitly,
+    when,
+    withEmptyLineAppended,
+    withNewlineAppended     // (legacy alias)
+} from "./index-internal.js"
+export type {
+    Template,
+    NestedString            // (legacy alias)
+} from "./index-internal.js"
+

package/src/primitives.ts

@@ -0,0 +1,31 @@
+/**
+ * Primitive functions on the {@link Template} type.
+ */
+
+import {eol, Template} from "./index-internal.js"
+
+const eolRegex = new RegExp(/\r*\n/)
+
+/**
+ * “Flattens” the given template to an array of strings, each of which represent exactly one line.
+ * Note: doesn't need to be exposed.
+ */
+export const flattened = (template: Template): string[] => {
+    if (template === undefined || template === null) {
+        return []
+    }    if (typeof template === "function") {
+        return flattened(template())
+    }
+    if (Array.isArray(template)) {
+        return template.map(flattened).reduce((arrL, arrR) => [...arrL, ...arrR], [])
+    }
+    return template.split(eolRegex)
+}
+
+
+/**
+ * @returns {string} - the given template joined as one string, taking care of proper EOLs.
+ */
+export const asString = (template: Template): string =>
+    flattened(template).map((line) => line + eol).join("")
+

package/src/strings.ts

@@ -0,0 +1,32 @@
+/**
+ * Purely string-related functions.
+ */
+
+/**
+ * @return the given array of strings but with commas added after each string except the last one.
+ */
+export const commaSeparated = (strings: string[])=>
+    strings.map((str, index) => `${str}${index + 1 < strings.length ? `,` : ``}`)
+
+/**
+ * Polyfill/shim for ES2015's String.prototype.repeat which doesn't work for some reason in the test...
+ * (Implementation uses the binary representation of n.)
+ * Note: doesn't need to be exposed.
+ */
+export const repeat = (str: string, n: number): string => {
+    let result = ""
+    while (n > 0) {
+        if (n % 2 === 1) {
+            result += str
+        }
+        if (n > 1) {
+            str += str
+        }
+        n >>= 1
+    }
+    return result
+}
+
+
+// TODO  more common string utils, e.g. withFirst{Upper|Lower}, etc.
+

package/src/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Types for templates.
+ */
+
+/**
+ * A type definition for “templates” that consist of a string, or an array of templates, or a thunk returning a template.
+ * Note that nesting can occur to arbitrary (finite) depth.
+ *
+ * @since version 0.3.0
+ */
+export type Template = string | undefined | null | Array<Template> | (() => Template)
+
+/**
+ * Legacy alias for the {@link Template} type definition.
+ * Note: this type might be deprecated and removed (per a major version) in the future.
+ */
+export type NestedString = Template
+