@thi.ng/strings 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-09-15T12:33:37Z
+- **Last updated**: 2023-09-19T10:42:50Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [3.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/strings@3.6.0) (2023-09-19)
+
+#### 🚀 Features
+
+- add escapeEntitiesNum() ([f921491](https://github.com/thi-ng/umbrella/commit/f921491))
+
 ## [3.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/strings@3.5.0) (2023-09-15)
 
 #### 🚀 Features

package/README.md

@@ -141,7 +141,7 @@ For Node.js REPL:
 const strings = await import("@thi.ng/strings");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.84 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.86 KB
 
 ## Dependencies
 
@@ -160,10 +160,12 @@ A selection:
 
 | Screenshot                                                                                                                 | Description                                                                                             | Live demo                                                 | Source                                                                                 |
 |:---------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------|:----------------------------------------------------------|:---------------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ascii-raymarch.jpg" width="240"/>      | ASCII art raymarching with thi.ng/shader-ast & thi.ng/text-canvas                                       | [Demo](https://demo.thi.ng/umbrella/ascii-raymarch/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ascii-raymarch)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/big-font.png" width="240"/>            | Large ASCII font text generator using @thi.ng/rdom                                                      | [Demo](https://demo.thi.ng/umbrella/big-font/)            | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/big-font)            |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/crypto-chart.png" width="240"/>        | Basic crypto-currency candle chart with multiple moving averages plots                                  | [Demo](https://demo.thi.ng/umbrella/crypto-chart/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/crypto-chart)        |
 |                                                                                                                            | Basic SPA example with atom-based UI router                                                             | [Demo](https://demo.thi.ng/umbrella/login-form/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/login-form)          |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/mastodon-feed.jpg" width="240"/>       | Mastodon API feed reader with support for different media types, fullscreen media modal, HTML rewriting | [Demo](https://demo.thi.ng/umbrella/mastodon-feed/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/mastodon-feed)       |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/render-audio.png" width="240"/>        | Generative audio synth offline renderer and WAV file export                                             | [Demo](https://demo.thi.ng/umbrella/render-audio/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/render-audio)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rstream-spreadsheet.png" width="240"/> | rstream based spreadsheet w/ S-expression formula DSL                                                   | [Demo](https://demo.thi.ng/umbrella/rstream-spreadsheet/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rstream-spreadsheet) |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/xml-converter.png" width="240"/>       | XML/HTML/SVG to hiccup/JS conversion                                                                    | [Demo](https://demo.thi.ng/umbrella/xml-converter/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/xml-converter)       |
 

package/entities.d.ts

@@ -9,6 +9,34 @@ export declare const RE_ENTITIES: RegExp;
 export declare const ENTITIES_REV: Record<string, string>;
 export declare const RE_ENTITIES_REV: RegExp;
 export declare const RE_ENTITIES_NUM: RegExp;
+/**
+ * Replaces all occurrences of character keys in {@link ENTITIES} with their
+ * named HTML entities.
+ *
+ * @remarks
+ * Only use this function when targetting HTML output. For XML/SVG etc. use
+ * {@link escapeEntitiesNum}.
+ *
+ * @param src
+ */
 export declare const escapeEntities: (src: string) => string;
+/**
+ * Similar to {@link escapeEntities}, but only uses _named_ entities for `&`,
+ * `<`, `>`, `'`, `"` and numeric entities for all others.
+ *
+ * @remarks
+ * This function is used as default by thi.ng/hiccup `serialize()` to escape
+ * characters and ensure compatibility with XML (which by default only supports
+ * named entities for the above 5 characters).
+ *
+ * @param src
+ */
+export declare const escapeEntitiesNum: (src: string) => string;
+/**
+ * Replace all known named and numeric entities with their original characters.
+ * Opposite op of {@link escapeEntities} and {@link escapeEntitiesNum}.
+ *
+ * @param src
+ */
 export declare const unescapeEntities: (src: string) => string;
 //# sourceMappingURL=entities.d.ts.map

package/entities.js

@@ -114,8 +114,38 @@ export const RE_ENTITIES = new RegExp(`[${Object.keys(ENTITIES).join("")}]`, "gu
 export const ENTITIES_REV = Object.entries(ENTITIES).reduce((acc, [k, v]) => ((acc[v] = k), acc), {});
 export const RE_ENTITIES_REV = new RegExp(`(${Object.keys(ENTITIES_REV).join("|")})`, "g");
 export const RE_ENTITIES_NUM = /&#(x?)([0-9a-f]+);/gi;
-const $esc = (re, index) => (src) => src.replace(re, (x) => index[x]);
-export const escapeEntities = $esc(RE_ENTITIES, ENTITIES);
+/**
+ * Replaces all occurrences of character keys in {@link ENTITIES} with their
+ * named HTML entities.
+ *
+ * @remarks
+ * Only use this function when targetting HTML output. For XML/SVG etc. use
+ * {@link escapeEntitiesNum}.
+ *
+ * @param src
+ */
+export const escapeEntities = (src) => src.replace(RE_ENTITIES, (x) => ENTITIES[x]);
+/**
+ * Similar to {@link escapeEntities}, but only uses _named_ entities for `&`,
+ * `<`, `>`, `'`, `"` and numeric entities for all others.
+ *
+ * @remarks
+ * This function is used as default by thi.ng/hiccup `serialize()` to escape
+ * characters and ensure compatibility with XML (which by default only supports
+ * named entities for the above 5 characters).
+ *
+ * @param src
+ */
+export const escapeEntitiesNum = (src) => src.replace(RE_ENTITIES, (x) => {
+    const code = x.charCodeAt(0);
+    return code < 128 ? ENTITIES[x] : `&#x${code.toString(16)};`;
+});
+/**
+ * Replace all known named and numeric entities with their original characters.
+ * Opposite op of {@link escapeEntities} and {@link escapeEntitiesNum}.
+ *
+ * @param src
+ */
 export const unescapeEntities = (src) => src
     .replace(RE_ENTITIES_REV, (x) => ENTITIES_REV[x])
     .replace(RE_ENTITIES_NUM, (_, hex, x) => String.fromCharCode(parseInt(x, hex ? 16 : 10)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/strings",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Various string formatting & utility functions",
   "type": "module",
   "module": "./index.js",
@@ -200,5 +200,5 @@
   "thi.ng": {
     "year": 2015
   },
-  "gitHead": "b2ef5a1b8932d067af4ec2fc7da03d59d6868dc7\n"
+  "gitHead": "c22e8996cee284ebe8ea88582beb1ab5fc6ee503\n"
 }