shelving 1.49.2 → 1.50.2

package/markup/render.d.ts

@@ -33,8 +33,3 @@ import type { MarkupOptions, MarkupNode } from "./types.js";
  * @returns ReactNode, i.e. either a complete `ReactElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
  */
 export declare function renderMarkup(content: string, options?: Partial<MarkupOptions>): MarkupNode;
-/**
- * Parse a text string as user-generated markup.
- * - Like `renderMarkup()` but only enables a subset of rules and applies `rel="nofollow ugc"` to all links.
- */
-export declare function renderUgcMarkup(content: string, options?: Partial<MarkupOptions>): MarkupNode;

package/markup/render.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-param-reassign */
 import { sanitizeLines } from "../index.js";
-import { MARKUP_RULES, MARKUP_RULES_UGC } from "./rules.js";
+import { MARKUP_RULES } from "./rules.js";
 /** Convert a string into an array of React nodes using a set of rules. */
 function renderString(content, options) {
     // If there's no context return the unmodified string.
@@ -154,15 +154,3 @@ const defaults = {
     rel: undefined,
     schemes: ["http:", "https:"],
 };
-/**
- * Parse a text string as user-generated markup.
- * - Like `renderMarkup()` but only enables a subset of rules and applies `rel="nofollow ugc"` to all links.
- */
-export function renderUgcMarkup(content, options) {
-    return renderString(sanitizeLines(content), { ...defaultsUgc, ...options });
-}
-const defaultsUgc = {
-    ...defaults,
-    rules: MARKUP_RULES_UGC,
-    rel: "nofollow ugc",
-};

package/markup/rules.d.ts

@@ -1,4 +1,115 @@
-import type { MarkupRule } from "./types.js";
+import type { MarkupRule, MarkupRuleMatcher } from "./types.js";
+export declare const getMarkupMatcher: (regexp: RegExp) => MarkupRuleMatcher;
+export declare const getMarkupBlockMatcher: (middle?: string, end?: string, start?: string) => MarkupRuleMatcher;
+export declare const getMarkupLineMatcher: (middle?: string, end?: string, start?: string) => MarkupRuleMatcher;
+export declare const getMarkupWrapMatcher: (chars: string, middle?: string) => MarkupRuleMatcher;
+/**
+ * Headings are single line only (don't allow multiline).
+ * - 1-6 hashes then 1+ spaces, then the title.
+ * - Same as Markdown syntax.
+ * - Markdown's underline syntax is not supported (for simplification).
+ */
+export declare const HEADING_RULE: MarkupRule;
+/**
+ * Horizontal rules
+ * - Same as Markdown syntax but also allows `•` bullet character (in addition to `-` dash, `+` plus, `*` asterisk, and `_` underscore).
+ * - Character must be repeated three (or more) times.
+ * - Character must be the same every time (can't mix)
+ * - Might have infinite number of spaces between the characters.
+ */
+export declare const HORIZONTAL_RULE: MarkupRule;
+export declare const UNORDERED_LIST_RULE: MarkupRule;
+export declare const ORDERED_LIST_RULE: MarkupRule;
+/**
+ * Blockquote block.
+ * - Same as Markdown's syntax.
+ * - Block continues until it finds a line that doesn't start with `>`
+ * - Quote indent symbol can be followed by zero or more spaces.
+ */
+export declare const BLOCKQUOTE_RULE: MarkupRule;
+/**
+ * Fenced code blocks
+ * - Same as Markdown syntax.
+ * - Closing fence must be exactly the same as the opening fence, and can be made of at least three "```" backticks or three `~~~` tildes.
+ * - If there's no closing fence the code block will run to the end of the current string.
+ * - Markdown-style four-space indent syntax is not supported (only fenced code, since it's easier to use).
+ */
+export declare const FENCED_CODE_RULE: MarkupRule;
+/**
+ * Paragraph.
+ * - When ordering rules, paragraph should go after other "block" context elements (because it has a very generous capture).
+ */
+export declare const PARAGRAPH_RULE: MarkupRule;
+/**
+ * Markdown-style link.
+ * - Link in standard Markdown format, e.g. `[http://google.com/maps](Google Maps)`
+ * - If no title is specified a cleaned up version of the URL will be used, e.g. `google.com/maps`
+ * - Does not need space before/after the link.
+ * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
+ * - For security only `http://` or `https://` links will work (if invalid the unparsed text will be returned).
+ */
+export declare const LINK_MARKUP: MarkupRule;
+/**
+ * Autolinked URL starts with `http:` or `https:` and matches an unlimited number of non-space characters.
+ * - If followed by space and then text in `()` round or `[]` square brackets that will be used as the title, e.g. `http://google.com/maps (Google Maps)` or `http://google.com/maps [Google Maps]` (this syntax is from Todoist and maybe other things too).
+ * - If no title is specified a cleaned up version of the URL will be used, e.g. `google.com/maps`
+ * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
+ * - For security only schemes that appear in the `options.schemes` will match (defaults to `http:` and `https:`).
+ */
+export declare const AUTOLINK_RULE: MarkupRule;
+/**
+ * Inline code.
+ * - Text surrounded by one or more "`" backtick tilde characters.
+ * - Unlike strong/emphasis first or last character of the element can be space, (e.g. `- abc -` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Same as Markdown syntax.
+ */
+export declare const CODE_RULE: MarkupRule;
+/**
+ * Inline strong.
+ * - Inline text wrapped in one or more `*` asterisks.
+ * - Must be surrounded by space (e.g. ` *abc* `) — so formatting cannot be applied inside a word (e.g. `a*b*c`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `* abc *` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
+ */
+export declare const STRONG_MARKUP: MarkupRule;
+/**
+ * Inline emphasis.
+ * - Inline text wrapped in one or more `_` underscore symbols.
+ * - Works inside words (e.g. `magi_carp_carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `_ abc _` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
+ */
+export declare const EMPHASIS_RULE: MarkupRule;
+/**
+ * Inserted text (`<ins>` tag),
+ * - Inline text wrapped in two or more `++` pluses.
+ * - Works inside words (e.g. `magi+karp+carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `+ abc +` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Markdown doesn't have this.
+ */
+export declare const INSERT_RULE: MarkupRule;
+/**
+ * Deleted text (`<del>` tag),
+ * - Inline text wrapped in two or more `--` hyphens or `~~` tildes.
+ * - Works inside words (e.g. `magi--karp--carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `-- abc --` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Markdown doesn't have this.
+ */
+export declare const DELETE_RULE: MarkupRule;
+/**
+ * Hard linebreak (`<br />` tag).
+ * - Any line break in a paragraph will become a hard `<br />` tag.
+ * - Different to Markdown:
+ *   - Markdown needs two spaces at the end of a line, any line break in a paragraph will be a `<br />` tag (lines without two spaces are not joined together).
+ *   - This is more intuitive (a linebreak becomes a linebreak is isn't silently ignored).
+ *   - This works better with textareas that wrap text (since manually breaking up long lines is no longer necessary).
+ */
+export declare const LINEBREAK_RULE: MarkupRule;
 /**
  * All markup rules.
  * - Syntax parsed by `renderMarkup()` is defined entirely by the list of rules (i.e. not by code).
@@ -9,5 +120,9 @@ import type { MarkupRule } from "./types.js";
  * - HTML tags and character entities are never allowed (our use cases generally require a locked-down subset of syntax).
  */
 export declare const MARKUP_RULES: MarkupRule[];
-/** Default markup rules for user-generated-content rendering. */
-export declare const MARKUP_RULES_UGC: MarkupRule[];
+/** Subset of markup rules that work in a block context. */
+export declare const MARKUP_RULES_BLOCK: MarkupRule[];
+/** Subset of markup rules that work in an inline context. */
+export declare const MARKUP_RULES_INLINE: MarkupRule[];
+/** Subset of markup rules that are relevant for collapsed shortform content. */
+export declare const MARKUP_RULES_SHORTFORM: MarkupRule[];

package/markup/rules.js

@@ -11,10 +11,10 @@ const WORDS = `\\S(?:[\\s\\S]*?\\S)?`; // Run of text that starts and ends with
 // Regular expressions.
 const REPLACE_INDENT = /^ {1,2}/gm;
 // Regular expression makers.
-const getMatcher = regexp => content => content.match(regexp);
-const getBlockMatcher = (middle = BLOCK, end = BLOCK_END, start = BLOCK_START) => getMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
-const getLineMatcher = (middle = LINE, end = LINE_END, start = LINE_START) => getMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
-const getWrapMatcher = (chars, middle = WORDS) => {
+export const getMarkupMatcher = regexp => content => content.match(regexp);
+export const getMarkupBlockMatcher = (middle = BLOCK, end = BLOCK_END, start = BLOCK_START) => getMarkupMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
+export const getMarkupLineMatcher = (middle = LINE, end = LINE_END, start = LINE_START) => getMarkupMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
+export const getMarkupWrapMatcher = (chars, middle = WORDS) => {
     const regexp = new RegExp(`(${chars})(${middle})\\1`);
     return content => content.match(regexp);
 };
@@ -24,8 +24,8 @@ const getWrapMatcher = (chars, middle = WORDS) => {
  * - Same as Markdown syntax.
  * - Markdown's underline syntax is not supported (for simplification).
  */
-const HEADING = {
-    match: getLineMatcher(`(#{1,6}) +(${LINE})`),
+export const HEADING_RULE = {
+    match: getMarkupLineMatcher(`(#{1,6}) +(${LINE})`),
     render: ([, prefix = "", children = ""]) => ({ type: `h${prefix.length}`, key: null, props: { children } }),
     contexts: ["block"],
     childContext: "inline",
@@ -37,8 +37,8 @@ const HEADING = {
  * - Character must be the same every time (can't mix)
  * - Might have infinite number of spaces between the characters.
  */
-const HR = {
-    match: getLineMatcher(`([${BULLETS}])(?: *\\1){2,}`),
+export const HORIZONTAL_RULE = {
+    match: getMarkupLineMatcher(`([${BULLETS}])(?: *\\1){2,}`),
     render: () => ({ type: "hr", key: null, props: {} }),
     contexts: ["block"],
 };
@@ -50,8 +50,8 @@ const HR = {
  * - Second-level list can be indented with 1-2 spaces.
  */
 const UNORDERED = `[${BULLETS}] +`; // Anything that can be a bullet (used for unordered lists and horizontal rules).
-const UL = {
-    match: getBlockMatcher(`${UNORDERED}(${BLOCK})`),
+export const UNORDERED_LIST_RULE = {
+    match: getMarkupBlockMatcher(`${UNORDERED}(${BLOCK})`),
     render: ([, list = ""]) => {
         const children = list.split(SPLIT_UL_ITEMS).map(mapUnorderedItem);
         return { type: "ul", key: null, props: { children } };
@@ -70,8 +70,8 @@ const mapUnorderedItem = (item, key) => {
  * - Second-level list can be indented with 1-3 spaces.
  */
 const ORDERED = "[0-9]+[.):] +"; // Number for a numbered list (e.g. `1.` or `2)` or `3:`)
-const OL = {
-    match: getBlockMatcher(`(${ORDERED}${BLOCK})`),
+export const ORDERED_LIST_RULE = {
+    match: getMarkupBlockMatcher(`(${ORDERED}${BLOCK})`),
     render: ([, list = ""]) => {
         const children = list.split(SPLIT_OL_ITEMS).map(mapOrderedItem);
         return { type: "ol", key: null, props: { children } };
@@ -95,8 +95,8 @@ const mapOrderedItem = (item, key) => {
  * - Block continues until it finds a line that doesn't start with `>`
  * - Quote indent symbol can be followed by zero or more spaces.
  */
-const BLOCKQUOTE = {
-    match: getLineMatcher(`(>${LINE}(?:\\n>${LINE})*)`),
+export const BLOCKQUOTE_RULE = {
+    match: getMarkupLineMatcher(`(>${LINE}(?:\\n>${LINE})*)`),
     render: ([, quote = ""]) => ({
         type: "blockquote",
         key: null,
@@ -113,9 +113,9 @@ const BLOCKQUOTE_LINES = /^>/gm;
  * - If there's no closing fence the code block will run to the end of the current string.
  * - Markdown-style four-space indent syntax is not supported (only fenced code, since it's easier to use).
  */
-const FENCED = {
+export const FENCED_CODE_RULE = {
     // Matcher has its own end that only stops when it reaches a matching closing fence or the end of the string.
-    match: getBlockMatcher(`(\`{3,}|~{3,}) *(${LINE})\\n(${BLOCK})`, `\\n\\1\\n+|\\n\\1$|$`),
+    match: getMarkupBlockMatcher(`(\`{3,}|~{3,}) *(${LINE})\\n(${BLOCK})`, `\\n\\1\\n+|\\n\\1$|$`),
     render: ([, , file, children]) => ({
         type: "pre",
         key: null,
@@ -133,8 +133,8 @@ const FENCED = {
  * Paragraph.
  * - When ordering rules, paragraph should go after other "block" context elements (because it has a very generous capture).
  */
-const PARAGRAPH = {
-    match: getBlockMatcher(` *(${BLOCK})`),
+export const PARAGRAPH_RULE = {
+    match: getMarkupBlockMatcher(` *(${BLOCK})`),
     render: ([, children]) => ({ type: `p`, key: null, props: { children } }),
     contexts: ["block"],
     childContext: "inline",
@@ -148,7 +148,7 @@ const PARAGRAPH = {
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only `http://` or `https://` links will work (if invalid the unparsed text will be returned).
  */
-const LINK = {
+export const LINK_MARKUP = {
     // Custom matcher to check the URL against the allowed schemes.
     match: (content, { schemes, url: base }) => {
         const matches = content.match(MATCH_LINK);
@@ -178,7 +178,7 @@ const MATCH_LINK = /\[([^\]]*?)\]\(([^)]*?)\)/;
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in the `options.schemes` will match (defaults to `http:` and `https:`).
  */
-const AUTOLINK = {
+export const AUTOLINK_RULE = {
     // Custom matcher to check the URL against the allowed schemes.
     match: (content, { schemes, url: base }) => {
         const matches = content.match(MATCH_AUTOLINK);
@@ -192,7 +192,7 @@ const AUTOLINK = {
             }
         }
     },
-    render: LINK.render,
+    render: LINK_MARKUP.render,
     contexts: ["inline", "list"],
     childContext: "link",
 };
@@ -204,8 +204,8 @@ const MATCH_AUTOLINK = /([a-z][a-z0-9-]*[a-z0-9]:\S+)(?: +(?:\(([^)]*?)\)|\[([^\
  * - Closing characters must exactly match opening characters.
  * - Same as Markdown syntax.
  */
-const CODE = {
-    match: getWrapMatcher("`+", BLOCK),
+export const CODE_RULE = {
+    match: getMarkupWrapMatcher("`+", BLOCK),
     render: ([, , children]) => ({ type: "code", key: null, props: { children } }),
     contexts: ["inline", "list"],
     priority: 10, // Higher priority than other inlines so it matches first before e.g. `strong` or `em` (from CommonMark spec: "Code span backticks have higher precedence than any other inline constructs except HTML tags and autolinks.")
@@ -218,8 +218,8 @@ const CODE = {
  * - Closing characters must exactly match opening characters.
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
  */
-const STRONG = {
-    match: getWrapMatcher("\\*+"),
+export const STRONG_MARKUP = {
+    match: getMarkupWrapMatcher("\\*+"),
     render: ([, , children]) => ({ type: "strong", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -232,36 +232,36 @@ const STRONG = {
  * - Closing characters must exactly match opening characters.
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
  */
-const EM = {
-    match: getWrapMatcher("_+"),
+export const EMPHASIS_RULE = {
+    match: getMarkupWrapMatcher("_+"),
     render: ([, , children]) => ({ type: "em", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
 };
 /**
  * Inserted text (`<ins>` tag),
- * - Inline text wrapped in one or more `+` pluses.
+ * - Inline text wrapped in two or more `++` pluses.
  * - Works inside words (e.g. `magi+karp+carp`).
  * - Whitespace cannot be the first or last character of the element (e.g. `+ abc +` will not work).
  * - Closing characters must exactly match opening characters.
  * - Markdown doesn't have this.
  */
-const INS = {
-    match: getWrapMatcher("\\++"),
+export const INSERT_RULE = {
+    match: getMarkupWrapMatcher("\\+\\++"),
     render: ([, , children]) => ({ type: "ins", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
 };
 /**
  * Deleted text (`<del>` tag),
- * - Inline text wrapped in one or more `~` tildes.
- * - Works inside words (e.g. `magi~karp~carp`).
- * - Whitespace cannot be the first or last character of the element (e.g. `~ abc ~` will not work).
+ * - Inline text wrapped in two or more `--` hyphens or `~~` tildes.
+ * - Works inside words (e.g. `magi--karp--carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `-- abc --` will not work).
  * - Closing characters must exactly match opening characters.
  * - Markdown doesn't have this.
  */
-const DEL = {
-    match: getWrapMatcher("~+"),
+export const DELETE_RULE = {
+    match: getMarkupWrapMatcher("--+|~~+"),
     render: ([, , children]) => ({ type: "del", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -274,8 +274,8 @@ const DEL = {
  *   - This is more intuitive (a linebreak becomes a linebreak is isn't silently ignored).
  *   - This works better with textareas that wrap text (since manually breaking up long lines is no longer necessary).
  */
-const BR = {
-    match: getMatcher(/\n/),
+export const LINEBREAK_RULE = {
+    match: getMarkupMatcher(/\n/),
     render: () => ({ type: "br", key: null, props: {} }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -289,6 +289,55 @@ const BR = {
  *   3. more aligned with smaller textboxes and editors that have line wrapping
  * - HTML tags and character entities are never allowed (our use cases generally require a locked-down subset of syntax).
  */
-export const MARKUP_RULES = [HEADING, HR, UL, OL, BLOCKQUOTE, FENCED, PARAGRAPH, LINK, AUTOLINK, CODE, STRONG, EM, INS, DEL, BR];
-/** Default markup rules for user-generated-content rendering. */
-export const MARKUP_RULES_UGC = [UL, OL, PARAGRAPH, LINK, AUTOLINK, CODE, STRONG, EM, INS, DEL, BR];
+export const MARKUP_RULES = [
+    HEADING_RULE,
+    HORIZONTAL_RULE,
+    UNORDERED_LIST_RULE,
+    ORDERED_LIST_RULE,
+    BLOCKQUOTE_RULE,
+    FENCED_CODE_RULE,
+    PARAGRAPH_RULE,
+    LINK_MARKUP,
+    AUTOLINK_RULE,
+    CODE_RULE,
+    STRONG_MARKUP,
+    EMPHASIS_RULE,
+    INSERT_RULE,
+    DELETE_RULE,
+    LINEBREAK_RULE,
+];
+/** Subset of markup rules that work in a block context. */
+export const MARKUP_RULES_BLOCK = [
+    HEADING_RULE,
+    HORIZONTAL_RULE,
+    UNORDERED_LIST_RULE,
+    ORDERED_LIST_RULE,
+    BLOCKQUOTE_RULE,
+    FENCED_CODE_RULE,
+    PARAGRAPH_RULE,
+];
+/** Subset of markup rules that work in an inline context. */
+export const MARKUP_RULES_INLINE = [
+    LINK_MARKUP,
+    AUTOLINK_RULE,
+    CODE_RULE,
+    STRONG_MARKUP,
+    EMPHASIS_RULE,
+    INSERT_RULE,
+    DELETE_RULE,
+    LINEBREAK_RULE,
+];
+/** Subset of markup rules that are relevant for collapsed shortform content. */
+export const MARKUP_RULES_SHORTFORM = [
+    UNORDERED_LIST_RULE,
+    ORDERED_LIST_RULE,
+    PARAGRAPH_RULE,
+    LINK_MARKUP,
+    AUTOLINK_RULE,
+    CODE_RULE,
+    STRONG_MARKUP,
+    EMPHASIS_RULE,
+    INSERT_RULE,
+    DELETE_RULE,
+    LINEBREAK_RULE,
+];

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.49.2",
+	"version": "1.50.2",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -25,9 +25,9 @@
 		"./db": "./db/index.js",
 		"./error": "./error/index.js",
 		"./feedback": "./feedback/index.js",
-		"./firestore/client": "./firestore-client/index.js",
-		"./firestore/lite": "./firestore-lite/index.js",
-		"./firestore/server": "./firestore-server/index.js",
+		"./firestore/client": "./firestore/client/index.js",
+		"./firestore/lite": "./firestore/lite/index.js",
+		"./firestore/server": "./firestore/server/index.js",
 		"./markup": "./markup/index.js",
 		"./provider": "./provider/index.js",
 		"./query": "./query/index.js",
@@ -61,22 +61,22 @@
 	"devDependencies": {
 		"@google-cloud/firestore": "^4.15.1",
 		"@types/jest": "^27.4.0",
-		"@types/react": "^17.0.38",
+		"@types/react": "^17.0.39",
 		"@types/react-dom": "^17.0.11",
-		"@typescript-eslint/eslint-plugin": "^5.9.1",
-		"@typescript-eslint/parser": "^5.9.1",
-		"eslint": "^8.7.0",
+		"@typescript-eslint/eslint-plugin": "^5.10.2",
+		"@typescript-eslint/parser": "^5.10.2",
+		"eslint": "^8.8.0",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-import": "^2.25.4",
 		"eslint-plugin-prettier": "^4.0.0",
-		"firebase": "^9.6.3",
-		"jest": "^27.4.7",
+		"firebase": "^9.6.6",
+		"jest": "^27.5.0",
 		"jest-ts-webcompat-resolver": "^1.0.0",
 		"prettier": "^2.5.1",
 		"react": "^17.0.2",
 		"react-dom": "^17.0.2",
 		"ts-jest": "^27.1.3",
-		"typescript": "^4.5.4"
+		"typescript": "^4.5.5"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=4.0.0",

package/stream/DataState.js

@@ -1,4 +1,4 @@
-import { withProp, transformProps, NOERROR, LOADING, awaitNext, getData } from "../util/index.js";
+import { withProp, transformData, NOERROR, LOADING, awaitNext, getData } from "../util/index.js";
 import { State } from "./State.js";
 /** State that stores a data object and has additional methods to help with that. */
 export class DataState extends State {
@@ -12,7 +12,7 @@ export class DataState extends State {
     }
     /** Update several props in this object. */
     update(updates) {
-        this.next(transformProps(this.data, updates));
+        this.next(transformData(this.data, updates));
     }
 }
 /** State that stores an optional data object and has additional methods to help with that. */
@@ -35,7 +35,7 @@ export class ResultState extends State {
     }
     /** Update several props in this object. */
     update(updates) {
-        this.next(transformProps(this.data, updates));
+        this.next(transformData(this.data, updates));
     }
     /** Delete this result. */
     delete() {

package/update/DataUpdate.js

@@ -1,4 +1,4 @@
-import { transformProps, isNullish } from "../util/index.js";
+import { transformData, isNullish } from "../util/index.js";
 import { Update } from "./Update.js";
 /** Update that can be applied to a data object to update its props. */
 export class DataUpdate extends Update {
@@ -11,7 +11,7 @@ export class DataUpdate extends Update {
         return new DataUpdate(!isNullish(key) ? { [key]: value } : {});
     }
     transform(existing) {
-        return transformProps(existing, this.updates);
+        return transformData(existing, this.updates);
     }
     /** Return a data update with a specific prop marked for update. */
     with(key, value) {

package/util/color.d.ts

@@ -1,5 +1,6 @@
 /** Things that can be converted to a `Color` instance. */
 export declare type PossibleColor = Color | string;
+export declare type PossibleOptionalColor = PossibleColor | null;
 /** Represent a color. */
 export declare class Color {
     readonly r: number;
@@ -20,7 +21,7 @@ export declare class Color {
 /** Convert a number or string to a color channel number that's within bounds (strings like `0a` or `ff` are parsed as hexadecimal). */
 export declare function getColorChannel(channel: number | string): number;
 /** Convert a possible color to a `Color` instance or `null` */
-export declare function toColor(color: PossibleColor): Color | null;
+export declare function toColor(color: unknown): Color | null;
 /** Convert a possible color to a `Color` instance */
 export declare function getColor(input: PossibleColor): Color;
 /** Is a color light? */

package/util/color.js

@@ -49,12 +49,14 @@ export function getColorChannel(channel) {
 export function toColor(color) {
     if (color instanceof Color)
         return color;
-    const hex3 = color.match(HEX3);
-    if (hex3)
-        return new Color(hex3[1], hex3[2], hex3[3]);
-    const hex6 = color.match(HEX6);
-    if (hex6)
-        return new Color(hex6[1], hex6[2], hex6[3], hex6[4]);
+    if (typeof color === "string") {
+        const hex3 = color.match(HEX3);
+        if (hex3)
+            return new Color(hex3[1], hex3[2], hex3[3]);
+        const hex6 = color.match(HEX6);
+        if (hex6)
+            return new Color(hex6[1], hex6[2], hex6[3], hex6[4]);
+    }
     return null;
 }
 /** Convert a possible color to a `Color` instance */

package/util/iterate.d.ts

@@ -52,6 +52,11 @@ export declare function yieldRange(start: number, end: number): Generator<number
  * - Checks `items.size` or `items.length` first to see if the limit is necessary.
  */
 export declare function limitItems<T>(items: Iterable<T>, limit: number): TypedIterable<T, void, void>;
+/**
+ * Reduce an iterable set of items using a reducer function.
+ */
+export declare function reduceItems<T, R>(items: Iterable<T>, reducer: (previous: R, item: T) => R, initial: R): R;
+export declare function reduceItems<T, R>(items: Iterable<T>, reducer: (previous: R | undefined, item: T) => R, initial?: R): R | undefined;
 /** Yield items from a source iterable until we hit a maximum iteration count. */
 export declare function yieldUntilLimit<T>(source: Iterable<T>, limit: number): Generator<T, void, void>;
 /** Infinite iterator that yields the result of calling a function with a given set of arguments. */

package/util/iterate.js

@@ -70,6 +70,12 @@ export function limitItems(items, limit) {
     const size = (_a = getKnownSize(items)) !== null && _a !== void 0 ? _a : Infinity;
     return size <= limit ? items : yieldUntilLimit(items, limit);
 }
+export function reduceItems(items, reducer, initial) {
+    let current = initial;
+    for (const item of items)
+        current = reducer(current, item);
+    return current;
+}
 /** Yield items from a source iterable until we hit a maximum iteration count. */
 export function* yieldUntilLimit(source, limit) {
     const iterator = source[Symbol.iterator]();

package/util/random.d.ts

@@ -2,9 +2,10 @@ import type { ImmutableArray } from "./array.js";
 /** Generate a random integer between two numbers. */
 export declare const getRandom: (min: number, max: number) => number;
 /**
- * Make a random key, e.g. "xs23rsdxe4mrugef"
+ * Make a random key, e.g. `xs23r34hhsdx` or `e4m29klrugef`
  * - Not designed to be cryptographically random!
  * - Will probably clash — if you're making a random ID, check for existence of the record before saving.
+ * - Designed to be semi-readable, doesn't use capital letters or `i` or `o` or `l` or `u`
  */
 export declare const getRandomKey: (length?: number) => string;
 /** Get a random character from a string. */

package/util/random.js

@@ -1,14 +1,15 @@
 import { yieldUntilLimit, yieldCall } from "./iterate.js";
-import { concatStrings } from "./string.js";
+import { joinStrings } from "./string.js";
 import { getDefined } from "./undefined.js";
 /** Generate a random integer between two numbers. */
 export const getRandom = (min, max) => Math.round(Math.random() * (max - min) + min);
 /**
- * Make a random key, e.g. "xs23rsdxe4mrugef"
+ * Make a random key, e.g. `xs23r34hhsdx` or `e4m29klrugef`
  * - Not designed to be cryptographically random!
  * - Will probably clash — if you're making a random ID, check for existence of the record before saving.
+ * - Designed to be semi-readable, doesn't use capital letters or `i` or `o` or `l` or `u`
  */
-export const getRandomKey = (length = 16) => concatStrings(yieldUntilLimit(yieldCall(getRandomCharacter, KEY_CHARS), length));
+export const getRandomKey = (length = 12) => joinStrings(yieldUntilLimit(yieldCall(getRandomCharacter, KEY_CHARS), length));
 const KEY_CHARS = "0123456789abcdefghjkmnpqrstvwxyz";
 /** Get a random character from a string. */
 export const getRandomCharacter = (str) => str[getRandom(0, str.length - 1)];

package/util/string.d.ts

@@ -16,8 +16,6 @@ export declare const isString: (v: unknown) => v is string;
  * -
  */
 export declare function toString(value: unknown): string;
-/** Concatenate a set of potential strings together. */
-export declare function concatStrings(values: Iterable<unknown>): string;
 /**
  * Convert an unknown value into a title string for user-facing use.
  * - Strings return the string.
@@ -32,6 +30,8 @@ export declare function concatStrings(values: Iterable<unknown>): string;
  * - Everything else returns `"Unknown"`
  */
 export declare function toTitle(value: unknown): string;
+/** Concatenate an iterable set of strings together. */
+export declare function joinStrings(strs: Iterable<string>, joiner?: string): string;
 /**
  * Sanitize unexpected characters from a string by:
  * - Stripping control characters.

package/util/string.js

@@ -32,13 +32,6 @@ export function toString(value) {
         return value.name || "function";
     return typeof value; // "symbol" etc.
 }
-/** Concatenate a set of potential strings together. */
-export function concatStrings(values) {
-    let output = "";
-    for (const value of values)
-        output += toString(value);
-    return output;
-}
 /**
  * Convert an unknown value into a title string for user-facing use.
  * - Strings return the string.
@@ -73,6 +66,13 @@ export function toTitle(value) {
         return "None";
     return "Unknown";
 }
+/** Concatenate an iterable set of strings together. */
+export function joinStrings(strs, joiner = "") {
+    let output = "";
+    for (const str of strs)
+        output += `${output.length ? joiner : ""}${str}`;
+    return output;
+}
 /**
  * Sanitize unexpected characters from a string by:
  * - Stripping control characters.

package/util/transform.d.ts

@@ -1,4 +1,3 @@
-import type { Entry } from "./entry.js";
 import type { ArrayType, ImmutableArray } from "./array.js";
 import type { ImmutableMap } from "./map.js";
 import { ImmutableObject } from "./object.js";
@@ -35,12 +34,6 @@ export declare function yieldTransformed<I, O>(items: Iterable<I>, transformer:
 export declare function transformArray<T extends ImmutableArray>(arr: T, transformer: Transformer<ArrayType<T>, ArrayType<T>>): T;
 export declare function transformArray<I, O>(arr: Iterable<I>, transformer: (v: I) => O): ImmutableArray<O>;
 export declare function transformArray<I, O>(arr: Iterable<I>, transformer: Transformer<I, O>): ImmutableArray<O>;
-/**
- * Transform the _values_ of a set of entries using a transformer.
- * @yield Transformed entry after calling transforming the new value for each entry.
- */
-export declare function yieldTransformedValues<I, O>(entries: Iterable<Entry<I>>, transformer: (v: I) => O): Iterable<Entry<O>>;
-export declare function yieldTransformedValues<I, O>(entries: Iterable<Entry<I>>, transformer: Transformer<I, O>): Iterable<Entry<O>>;
 /**
  * Transform the _values_ of a map using a transformer.
  * @return New map after transforming its values.
@@ -65,7 +58,7 @@ export declare type PropTransformers<T extends Data> = {
  * Transform the props of a data object using a set of transformers for its props.
  * @returns New object with changed props (or the same object if no changes were made).
  */
-export declare function transformProps<T extends Data>(existing: T, transformers: PropTransformers<T>): T;
+export declare function transformData<T extends Data>(existing: T, transformers: PropTransformers<T>): T;
 /** Set of named transformers for a a map-like object. */
 export declare type EntryTransformers<T> = ImmutableObject<Transformer<T | undefined, T>>;
 /** Transform some of the entries of a map-like object using a set of named transformers. */

package/util/transform.js

@@ -16,18 +16,18 @@ export function* yieldTransformed(items, transformer) {
 export function transformArray(arr, transformer) {
     return Array.from(yieldTransformed(arr, transformer));
 }
-export function* yieldTransformedValues(entries, transformer) {
+function* _yieldTransformedValues(entries, transformer) {
     for (const [k, v] of entries)
         yield [k, transform(v, transformer)];
 }
 export function transformMap(map, transformer) {
-    return new Map(yieldTransformedValues(map, transformer));
+    return new Map(_yieldTransformedValues(map, transformer));
 }
 export function transformObject(obj, transformer) {
-    return Object.fromEntries(yieldTransformedValues(Object.entries(obj), transformer));
+    return Object.fromEntries(_yieldTransformedValues(Object.entries(obj), transformer));
 }
 /** Apply transformers to the props of a data object and yield any props that changed. */
-function* yieldTransformedProps(existing, transformers) {
+function* _yieldTransformedProps(existing, transformers) {
     for (const [k, v] of toProps(transformers))
         yield [k, transform(existing[k], v)];
 }
@@ -35,15 +35,15 @@ function* yieldTransformedProps(existing, transformers) {
  * Transform the props of a data object using a set of transformers for its props.
  * @returns New object with changed props (or the same object if no changes were made).
  */
-export function transformProps(existing, transformers) {
-    return Object.fromEntries(yieldMerged(toProps(existing), yieldTransformedProps(existing, transformers)));
+export function transformData(existing, transformers) {
+    return Object.fromEntries(yieldMerged(toProps(existing), _yieldTransformedProps(existing, transformers)));
 }
 /** Apply named transformers to the entries of a map-like object and yield any entries that changed. */
-function* yieldTransformedEntries(existing, updates) {
+function* _yieldTransformedEntries(existing, updates) {
     for (const [k, t] of Object.entries(updates))
         yield [k, transform(existing[k], t)];
 }
 /** Transform some of the entries of a map-like object using a set of named transformers. */
 export function transformEntries(existing, updates, deletes) {
-    return Object.fromEntries(yieldFiltered(yieldMerged(Object.entries(existing), yieldTransformedEntries(existing, updates)), isKeyInArray, deletes));
+    return Object.fromEntries(yieldFiltered(yieldMerged(Object.entries(existing), _yieldTransformedEntries(existing, updates)), isKeyInArray, deletes));
 }

package/util/undefined.js

@@ -1,4 +1,4 @@
-import { RequiredError } from "..";
+import { RequiredError } from "../error/index.js";
 /** Is a value undefined? */
 export const isUndefined = (v) => v === undefined;
 /** Is a value defined? */

package/util/validate.d.ts

@@ -1,5 +1,5 @@
 import type { Entry } from "./entry.js";
-import { Data, Prop, Result } from "./data.js";
+import { Data, Result } from "./data.js";
 /** Object that can validate an unknown value with its `validate()` method. */
 export interface Validatable<T> {
     /**
@@ -50,14 +50,6 @@ export declare function validateItems<T>(unsafeItems: Iterable<unknown>, validat
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
 export declare function validateValues<T>(unsafeValues: Iterable<Entry>, validator: Validator<T>): Generator<Entry<T>, void>;
-/**
- * Validate a set of object props with a set of validators.
- *
- * @yield Valid entries for each specified validator.
- * @throw InvalidFeedback if one or more entries did not validate.
- * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
- */
-export declare function validateProps<T extends Data>(unsafeData: Data, validators: Validators<T>): Generator<Prop<T>, void>;
 /**
  * Validate an entire object with a set of validators.
  * - Defined props in the object will be validated against the corresponding validator.
@@ -69,7 +61,7 @@ export declare function validateProps<T extends Data>(unsafeData: Data, validato
  */
 export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>): T;
 /**
- * Validate a data result.
+ * Validate a data result against a validator for that data.
  * @return Valid object or `null`
  */
 export declare function validateResult<T extends Data>(unsafeResult: unknown, validator: Validator<T>): Result<T>;

package/util/validate.js

@@ -1,5 +1,6 @@
 import { Feedback, InvalidFeedback } from "../feedback/index.js";
 import { isData, toProps } from "./data.js";
+import { isNullish } from "./null.js";
 /** Is a given value a validator? */
 export const isValidator = (v) => typeof v === "function" || (isData(v) && typeof v.validate === "function");
 /** Validate an unknown value with a validator. */
@@ -56,6 +57,18 @@ export function* validateValues(unsafeValues, validator) {
     if (invalid)
         throw new InvalidFeedback("Invalid items", details);
 }
+/**
+ * Validate an entire object with a set of validators.
+ * - Defined props in the object will be validated against the corresponding validator.
+ * - `undefined` props in the object will be set to the default value of that prop.
+ *
+ * @return Valid object.
+ * @throw InvalidFeedback if one or more entries did not validate.
+ * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
+ */
+export function validateData(unsafeData, validators) {
+    return Object.fromEntries(_yieldValidatedProps(unsafeData, validators));
+}
 /**
  * Validate a set of object props with a set of validators.
  *
@@ -63,7 +76,7 @@ export function* validateValues(unsafeValues, validator) {
  * @throw InvalidFeedback if one or more entries did not validate.
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
-export function* validateProps(unsafeData, validators) {
+function* _yieldValidatedProps(unsafeData, validators) {
     let invalid = false;
     const details = {};
     for (const [k, validator] of toProps(validators)) {
@@ -83,21 +96,9 @@ export function* validateProps(unsafeData, validators) {
         throw new InvalidFeedback("Invalid data", details);
 }
 /**
- * Validate an entire object with a set of validators.
- * - Defined props in the object will be validated against the corresponding validator.
- * - `undefined` props in the object will be set to the default value of that prop.
- *
- * @return Valid object.
- * @throw InvalidFeedback if one or more entries did not validate.
- * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
- */
-export function validateData(unsafeData, validators) {
-    return Object.fromEntries(validateProps(unsafeData, validators));
-}
-/**
- * Validate a data result.
+ * Validate a data result against a validator for that data.
  * @return Valid object or `null`
  */
 export function validateResult(unsafeResult, validator) {
-    return unsafeResult === null || unsafeResult === undefined ? validate(unsafeResult, validator) : null;
+    return !isNullish(unsafeResult) ? validate(unsafeResult, validator) : null;
 }