@domchristie/composite - npm Package Compare versions

Comparing version 0.4.0 to 0.5.0

composite.js

@@ -12,5 +12,5 @@ /**
       : String(template)
-  return (new Function('html', 'raw', ...Object.keys(props),
+  return (new Function(...Object.keys(exports), ...Object.keys(props),
     `return html\`${template}\``
-  ))(html, raw, ...Object.values(props))
+  ))(...Object.values(exports), ...Object.values(props))
 }
@@ -26,3 +26,3 @@
  */
-function html (strings, ...values) {
+export function html (strings, ...values) {
   return strings.reduce((result, string, i) => {
@@ -36,2 +36,12 @@ const value = values[i] != null
 
+/**
+ * Escapes special characters in a string for use in HTML.
+ * The characters escaped are: & < > " ' ` = /
+ *
+ * @param {string} string - The input string to escape.
+ * @returns {string} - The escaped string.
+ */
+export function escape (string) {
+  return String(string).replace(/[&<>"'`=\/]/g, (s) => entities[s])
+}
 const entities = {
@@ -49,14 +59,8 @@ '&': '&amp;',
 /**
- * Escapes special characters in a string for use in HTML.
- * The characters escaped are: & < > " ' ` = /
+ * Unescapes a given HTML-encoded string.
  *
- * @param {string} string - The input string to escape.
- * @returns {string} - The escaped string.
+ * @param {string} string - The HTML-encoded string to unescape.
+ * @returns {string} - The unescaped string.
  */
-export function escape (string) {
-  return String(string).replace(/[&<>"'`=\/]/g, (s) => entities[s])
-}
-
-let textarea
-function unescape (string) {
+export function unescape (string) {
   textarea = textarea || document.createElement('textarea')
@@ -66,2 +70,3 @@ textarea.innerHTML = string
 }
+let textarea
 
@@ -79,1 +84,3 @@ /**
 class RawString extends String { raw = true }
+
+const exports = { fill, html, escape, unescape, raw }

package.json

 {
   "name": "@domchristie/composite",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A hybrid client-side/server-side approach to generating dynamic HTML.",
   "main": "composite.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "docs": "npx documentation readme composite.js -s \"API Docs\" --github"
   },
@@ -14,3 +15,6 @@ "keywords": [
   "author": "Dom Christie",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "documentation": "^14.0.3"
+  }
 }

README.md

 # 🦷 Composite
 
-A hybrid client-side/server-side approach to generating dynamic HTML.
+A tiny web template system for the browser.
 
@@ -9,3 +9,3 @@ Compose your HTML in `<template>` elements. Use placeholders (`${…}`) to mark dynamic content. Call `fill` to generate a new HTML string which interpolates the template's content with the given properties.
 
-```
+```sh
 npm install @domchristie/composite
@@ -27,14 +27,89 @@ ```
 
-## Escaping HTML and Unescaping with `raw`
+## API Docs
 
-Template placeholders are automatically HTML-escaped to prevent cross-site scripting (XSS) attacks. To output content without escaping, use `raw`:
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-```html
-<template id="hello">
-  <h1>${raw(greeting)}, ${name}!</h1>
-</template>
-```
+#### Table of Contents
 
+*   [fill](#fill)
+    *   [Parameters](#parameters)
+*   [html](#html)
+    *   [Parameters](#parameters-1)
+*   [escape](#escape)
+    *   [Parameters](#parameters-2)
+*   [unescape](#unescape)
+    *   [Parameters](#parameters-3)
+*   [raw](#raw)
+    *   [Parameters](#parameters-4)
+
+### fill
+
+[composite.js:8-15](https://github.com/domchristie/composite/blob/47ceebce8126d3ea0fadfa8f7b21ee5db81d3a0d/composite.js#L8-L15 "Source code on GitHub")
+
+Renders a template with given properties.
+
+#### Parameters
+
+*   `template` **(HTMLTemplateElement | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** The HTML template to be rendered.
+*   `props` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** An object containing properties to be interpolated into the template.
+
+Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The rendered HTML string with properties interpolated.
+
+### html
+
+[composite.js:25-32](https://github.com/domchristie/composite/blob/47ceebce8126d3ea0fadfa8f7b21ee5db81d3a0d/composite.js#L25-L32 "Source code on GitHub")
+
+A tag function for template literals that escapes HTML special characters in
+values unless they are marked as raw.
+
+#### Parameters
+
+*   `strings` **TemplateStringsArray** An array of string literals.
+*   `values` **...any** The values to be interpolated into the template.
+
+Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The final string with values safely interpolated.
+
+### escape
+
+[composite.js:41-43](https://github.com/domchristie/composite/blob/47ceebce8126d3ea0fadfa8f7b21ee5db81d3a0d/composite.js#L41-L43 "Source code on GitHub")
+
+Escapes special characters in a string for use in HTML.
+The characters escaped are: & < > " ' \` = /
+
+#### Parameters
+
+*   `string` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The input string to escape.
+
+Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The escaped string.
+
+### unescape
+
+[composite.js:61-65](https://github.com/domchristie/composite/blob/47ceebce8126d3ea0fadfa8f7b21ee5db81d3a0d/composite.js#L61-L65 "Source code on GitHub")
+
+Unescapes a given HTML-encoded string.
+
+#### Parameters
+
+*   `string` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The HTML-encoded string to unescape.
+
+Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The unescaped string.
+
+### raw
+
+[composite.js:74-76](https://github.com/domchristie/composite/blob/47ceebce8126d3ea0fadfa8f7b21ee5db81d3a0d/composite.js#L74-L76 "Source code on GitHub")
+
+Marks a string as raw HTML to prevent escaping of special characters.
+
+#### Parameters
+
+*   `html` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The HTML string to wrap.
+
+Returns **RawString** The wrapped HTML string as a RawString object.
+
+## unsafe-eval
+
+Composite uses `new Function` to generate HTML from templates. This approach can fail when using strict Content Security Policies (CSPs).
+
 ## License
 
 Copyright © 2024+ Dom Christie and released under the MIT license.

No alert changes

Improved metrics

Total package byte prevSize

10250

increased by51.63%

Lines of code

114

increased by6.54%

Number of lines in readme file

114

increased by192.31%

Worsened metrics

Dev dependency count

1

increased byInfinity%

No dependency changes