shelving 1.29.0 → 1.30.3

package/db/Database.d.ts

@@ -56,7 +56,9 @@ export declare class DataQuery<T extends Data = Data> extends Query<T> implement
     get count(): number | PromiseLike<number>;
     /**
      * Get an entry for the first document matching this query.
-     * @return Entry in `[id, data]` format for the first document, or `undefined` if there are no matching documents (possibly promised).
+     *
+     * @return Entry in `[id, data]` format for the first document.
+     * @throws RequiredError if there were no results for this query.
      */
     get first(): Entry<T> | undefined | PromiseLike<Entry<T> | undefined>;
     /**
@@ -100,6 +102,8 @@ export declare class DataQuery<T extends Data = Data> extends Query<T> implement
     validate(unsafeEntries: Results): Results<T>;
     toString(): string;
 }
+/** Get the data for a document from a result for that document. */
+export declare function getQueryFirst<T extends Data>(results: Results<T>, ref: DataQuery<T>): Entry<T>;
 /** A document reference within a specific database. */
 export declare class DataDocument<T extends Data = Data> implements Observable<Result<T>>, Validatable<T> {
     readonly provider: Provider;

package/db/Database.js

@@ -2,7 +2,7 @@ import { callAsync, getFirstItem, throwAsync, validate, toMap, countItems, Trans
 import { DataUpdate, Update } from "../update/index.js";
 import { Feedback, InvalidFeedback } from "../feedback/index.js";
 import { Filters, Query, EqualFilter } from "../query/index.js";
-import { DocumentRequiredError, DocumentValidationError, QueryValidationError } from "./errors.js";
+import { DocumentRequiredError, DocumentValidationError, QueryRequiredError, QueryValidationError } from "./errors.js";
 import { DocumentDelete, DocumentSet, DocumentUpdate, Writes } from "./Write.js";
 /**
  * Combines a database model and a provider.
@@ -81,10 +81,12 @@ export class DataQuery extends Query {
     }
     /**
      * Get an entry for the first document matching this query.
-     * @return Entry in `[id, data]` format for the first document, or `undefined` if there are no matching documents (possibly promised).
+     *
+     * @return Entry in `[id, data]` format for the first document.
+     * @throws RequiredError if there were no results for this query.
      */
     get first() {
-        return callAsync(getFirstItem, this.max(1).results);
+        return callAsync(getQueryFirst, this.max(1).results, this);
     }
     /**
      * Subscribe to all matching documents.
@@ -158,6 +160,13 @@ export class DataQuery extends Query {
         return `${this.collection}?${super.toString()}`;
     }
 }
+/** Get the data for a document from a result for that document. */
+export function getQueryFirst(results, ref) {
+    const first = getFirstItem(results);
+    if (first)
+        return first;
+    throw new QueryRequiredError(ref);
+}
 /** A document reference within a specific database. */
 export class DataDocument {
     constructor(provider, validator, collection, id) {

package/db/errors.d.ts

@@ -7,6 +7,11 @@ export declare class DocumentRequiredError<T extends Data> extends RequiredError
     ref: DataDocument<T>;
     constructor(ref: DataDocument<T>);
 }
+/** Thrown if a query doesn't exist. */
+export declare class QueryRequiredError<T extends Data> extends RequiredError {
+    ref: DataQuery<T>;
+    constructor(ref: DataQuery<T>);
+}
 /** Thrown if a document can't validate. */
 export declare class DocumentValidationError<T extends Data> extends ValidationError {
     ref: DataDocument<T>;

package/db/errors.js

@@ -7,6 +7,14 @@ export class DocumentRequiredError extends RequiredError {
     }
 }
 DocumentRequiredError.prototype.name = "DocumentRequiredError";
+/** Thrown if a query doesn't exist. */
+export class QueryRequiredError extends RequiredError {
+    constructor(ref) {
+        super(`Query "${ref.toString()}" has no results`);
+        this.ref = ref;
+    }
+}
+QueryRequiredError.prototype.name = "QueryRequiredError";
 /** Thrown if a document can't validate. */
 export class DocumentValidationError extends ValidationError {
     constructor(ref, feedback) {

package/markup/helpers.d.ts

@@ -7,7 +7,7 @@ import type { MarkupElement, MarkupNode } from "./types.js";
  *
  * @example `- Item with *strong*\n- Item with _em_` becomes `Item with strong Item with em`
  */
-export declare const nodeToText: (node: MarkupNode) => string;
+export declare function nodeToText(node: MarkupNode): string;
 /**
  * Take a Markup JSX node and convert it to an HTML string.
  *
@@ -17,13 +17,7 @@ export declare const nodeToText: (node: MarkupNode) => string;
  *
  * @example `- Item with *strong*\n- Item with _em_` becomes `<ul><li>Item with <strong>strong</strong></li><li>Item with <em>em</em></ul>`
  */
-export declare const nodeToHtml: (node: MarkupNode) => string;
-/**
- * Clean an input string.
- * - Allows our future RegExps to be less fussy (e.g. allowing for whitespace at the end of lines).
- * - Converts tabs and any other rogue whitespace (line feeds, obscure Unicode things) to whitespaces.
- */
-export declare const cleanMarkup: (content: string) => string;
+export declare function nodeToHtml(node: MarkupNode): string;
 /**
  * Iterate through all elements in a node.
  * - This is useful if you, e.g. want to apply a `className` to all `<h1>` elements, or make a list of all URLs found in a Node.

package/markup/helpers.js

@@ -7,7 +7,7 @@ import { serialise } from "../util/index.js";
  *
  * @example `- Item with *strong*\n- Item with _em_` becomes `Item with strong Item with em`
  */
-export const nodeToText = (node) => {
+export function nodeToText(node) {
     if (typeof node === "string")
         return node;
     if (node instanceof Array)
@@ -15,7 +15,7 @@ export const nodeToText = (node) => {
     if (typeof node === "object" && node)
         return nodeToText(node.props.children);
     return "";
-};
+}
 /**
  * Take a Markup JSX node and convert it to an HTML string.
  *
@@ -25,7 +25,7 @@ export const nodeToText = (node) => {
  *
  * @example `- Item with *strong*\n- Item with _em_` becomes `<ul><li>Item with <strong>strong</strong></li><li>Item with <em>em</em></ul>`
  */
-export const nodeToHtml = (node) => {
+export function nodeToHtml(node) {
     if (typeof node === "string")
         return node;
     if (node instanceof Array)
@@ -36,7 +36,7 @@ export const nodeToHtml = (node) => {
         return `<${type}${strings.length ? ` ${strings.join(" ")}` : ""}>${nodeToHtml(children)}</${type}>`;
     }
     return "";
-};
+}
 const propToString = ([key, value]) => value === true
     ? key
     : typeof value === "number" && Number.isFinite(value)
@@ -44,25 +44,6 @@ const propToString = ([key, value]) => value === true
         : typeof value === "string"
             ? `${key}=${serialise(value)}`
             : "";
-// Regular expressions used for preprocessing.
-const ROGUE_WHITESPACE = /[^\S\n ]/g; // Match whitespace that isn't "\n" line feed or ` ` space (includes tabs).
-const ROGUE_PARAGRAPHS = /\u2029/g; // Match newlines that use "\r".
-const ROGUE_NEWLINES = /\r\n?|\u2028/g; // Match newlines that use "\r".
-const TRAILING_SPACES = / +$/gm; // Match trailing spaces on a line.
-// eslint-disable-next-line no-control-regex
-const CONTROL_CHARS = /[\x00-\x09\x0B-\x1F\x7F-\x9F]/g; // Match all control characters (00-1F, 7F-9F) except `\x0A` `\n` line feed (security).
-/**
- * Clean an input string.
- * - Allows our future RegExps to be less fussy (e.g. allowing for whitespace at the end of lines).
- * - Converts tabs and any other rogue whitespace (line feeds, obscure Unicode things) to whitespaces.
- */
-export const cleanMarkup = (content) => content
-    .replace(ROGUE_PARAGRAPHS, "\n\n") // Change weird new paragraph separators to standard "\n\n"
-    .replace(ROGUE_NEWLINES, "\n") // Change weird newlines to standard "\n"
-    .replace(ROGUE_WHITESPACE, " ") // Change obscure whitespace characters (e.g. tab and line-feed) to whitespace.
-    .replace(TRAILING_SPACES, "") // Strip trailing whitespaces on any lines.
-    .replace(CONTROL_CHARS, "") // Strip trailing spaces on any lines.
-    .trimStart(); // Trim the start (including leading newlines).
 /**
  * Iterate through all elements in a node.
  * - This is useful if you, e.g. want to apply a `className` to all `<h1>` elements, or make a list of all URLs found in a Node.

package/markup/render.d.ts

@@ -32,9 +32,9 @@ 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 const renderMarkup: (content: string, options?: Partial<MarkupOptions> | undefined) => MarkupNode;
+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 const renderUgcMarkup: (content: string, options?: Partial<MarkupOptions> | undefined) => MarkupNode;
+export declare function renderUgcMarkup(content: string, options?: Partial<MarkupOptions>): MarkupNode;

package/markup/render.js

@@ -1,8 +1,8 @@
 /* eslint-disable no-param-reassign */
-import { cleanMarkup } from "./helpers.js";
+import { sanitizeLines } from "../index.js";
 import { MARKUP_RULES, MARKUP_RULES_UGC } from "./rules.js";
 /** Convert a string into an array of React nodes using a set of rules. */
-const renderString = (content, options) => {
+function renderString(content, options) {
     // If there's no context return the unmodified string.
     if (!options.context)
         return content;
@@ -60,14 +60,14 @@ const renderString = (content, options) => {
     }
     // If there's only one node return the single node (otherwise return the entire array).
     return !nodes.length ? null : nodes.length === 1 ? nodes[0] : nodes;
-};
+}
 /**
  * Append a JSX node to a list of JSX nodes.
  * - Sets a generated `element.key` for JSX elements (based on `nodes.length`)
  * - JSX nodes can be arrays of nodes — these will be flattened directly into the nodes list.
  * - Nodes array is modified in place (not returned).
  */
-const appendNode = (nodes, node) => {
+function appendNode(nodes, node) {
     if (!node) {
         // No need to append null, undefined, or empty string.
         return;
@@ -92,12 +92,12 @@ const appendNode = (nodes, node) => {
         // Append the node.
         nodes.push(node);
     }
-};
+}
 /**
  * Render a JSX node
  * - Recursively renders the children of the node using the current options.
  */
-const renderNode = (node, options) => {
+function renderNode(node, options) {
     if (typeof node === "string")
         return renderString(node, options);
     if (node instanceof Array)
@@ -109,7 +109,7 @@ const renderNode = (node, options) => {
         return node;
     }
     return node;
-};
+}
 const REACT_SECURITY_SYMBOL = Symbol.for("react.element");
 /**
  * Parse a text string as Markdownish syntax and render it as a JSX node.
@@ -144,7 +144,9 @@ const REACT_SECURITY_SYMBOL = Symbol.for("react.element");
  *
  * @returns ReactNode, i.e. either a complete `ReactElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
  */
-export const renderMarkup = (content, options) => renderString(cleanMarkup(content), { ...defaults, ...options });
+export function renderMarkup(content, options) {
+    return renderString(sanitizeLines(content), { ...defaults, ...options });
+}
 const defaults = {
     rules: MARKUP_RULES,
     context: "block",
@@ -156,7 +158,9 @@ const defaults = {
  * 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 const renderUgcMarkup = (content, options) => renderString(cleanMarkup(content), { ...defaultsUgc, ...options });
+export function renderUgcMarkup(content, options) {
+    return renderString(sanitizeLines(content), { ...defaultsUgc, ...options });
+}
 const defaultsUgc = {
     ...defaults,
     rules: MARKUP_RULES_UGC,

package/markup/rules.js

@@ -7,16 +7,14 @@ const BLOCK = "[\\s\\S]*?"; // Match block of content (including newlines so don
 const BLOCK_START = "^\\n*|\\n+"; // Starts at start of a block (one or more linebreak or start of string).
 const BLOCK_END = "\\n*$|\\n\\n+"; // End of a block (two or more linebreaks or end of string).
 const BULLETS = "-*•+"; // Anything that can be a bullet (used for unordered lists and horizontal rules).
-const UNORDERED = `[${BULLETS}] +`; // Anything that can be a bullet (used for unordered lists and horizontal rules).
-const ORDERED = "[0-9]+[.):] +"; // Number for a numbered list (e.g. `1.` or `2)` or `3:`)
 const WORDS = `\\S(?:[\\s\\S]*?\\S)?`; // Run of text that starts and ends with non-space characters (possibly multi-line).
 // Regular expressions.
 const REPLACE_INDENT = /^ {1,2}/gm;
 // Regular expression makers.
-const createMatcher = (regexp) => content => content.match(regexp);
-const createBlockMatcher = (middle = BLOCK, end = BLOCK_END, start = BLOCK_START) => createMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
-const createLineMatcher = (middle = LINE, end = LINE_END, start = LINE_START) => createMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
-const createWrapMatcher = (chars, middle = WORDS) => {
+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) => {
     const regexp = new RegExp(`(${chars})(${middle})\\1`);
     return content => content.match(regexp);
 };
@@ -27,7 +25,7 @@ const createWrapMatcher = (chars, middle = WORDS) => {
  * - Markdown's underline syntax is not supported (for simplification).
  */
 const HEADING = {
-    match: createLineMatcher(`(#{1,6}) +(${LINE})`),
+    match: getLineMatcher(`(#{1,6}) +(${LINE})`),
     render: ([, prefix = "", children = ""]) => ({ type: `h${prefix.length}`, key: null, props: { children } }),
     contexts: ["block"],
     childContext: "inline",
@@ -40,7 +38,7 @@ const HEADING = {
  * - Might have infinite number of spaces between the characters.
  */
 const HR = {
-    match: createLineMatcher(`([${BULLETS}])(?: *\\1){2,}`),
+    match: getLineMatcher(`([${BULLETS}])(?: *\\1){2,}`),
     render: () => ({ type: "hr", key: null, props: {} }),
     contexts: ["block"],
 };
@@ -51,8 +49,9 @@ const HR = {
  * - Lists can be created with `•` bullet characters (in addition to `-` dash, `+` plus, and `*` asterisk).
  * - 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: createBlockMatcher(`${UNORDERED}(${BLOCK})`),
+    match: getBlockMatcher(`${UNORDERED}(${BLOCK})`),
     render: ([, list = ""]) => {
         const children = list.split(SPLIT_UL_ITEMS).map(mapUnorderedItem);
         return { type: "ul", key: null, props: { children } };
@@ -70,8 +69,9 @@ const mapUnorderedItem = (item, key) => {
  * - No leading spaces are allowed for the top-level list.
  * - 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: createBlockMatcher(`(${ORDERED}${BLOCK})`),
+    match: getBlockMatcher(`(${ORDERED}${BLOCK})`),
     render: ([, list = ""]) => {
         const children = list.split(SPLIT_OL_ITEMS).map(mapOrderedItem);
         return { type: "ol", key: null, props: { children } };
@@ -96,7 +96,7 @@ const mapOrderedItem = (item, key) => {
  * - Quote indent symbol can be followed by zero or more spaces.
  */
 const BLOCKQUOTE = {
-    match: createLineMatcher(`(>${LINE}(?:\\n>${LINE})*)`),
+    match: getLineMatcher(`(>${LINE}(?:\\n>${LINE})*)`),
     render: ([, quote = ""]) => ({
         type: "blockquote",
         key: null,
@@ -115,7 +115,7 @@ const BLOCKQUOTE_LINES = /^>/gm;
  */
 const FENCED = {
     // Matcher has its own end that only stops when it reaches a matching closing fence or the end of the string.
-    match: createBlockMatcher(`(\`{3,}|~{3,}) *(${LINE})\\n(${BLOCK})`, `\\n\\1\\n+|\\n\\1$|$`),
+    match: getBlockMatcher(`(\`{3,}|~{3,}) *(${LINE})\\n(${BLOCK})`, `\\n\\1\\n+|\\n\\1$|$`),
     render: ([, , file, children]) => ({
         type: "pre",
         key: null,
@@ -134,7 +134,7 @@ const FENCED = {
  * - When ordering rules, paragraph should go after other "block" context elements (because it has a very generous capture).
  */
 const PARAGRAPH = {
-    match: createBlockMatcher(` *(${BLOCK})`),
+    match: getBlockMatcher(` *(${BLOCK})`),
     render: ([, children]) => ({ type: `p`, key: null, props: { children } }),
     contexts: ["block"],
     childContext: "inline",
@@ -205,7 +205,7 @@ const MATCH_AUTOLINK = /([a-z][a-z0-9-]*[a-z0-9]:\S+)(?: +(?:\(([^)]*?)\)|\[([^\
  * - Same as Markdown syntax.
  */
 const CODE = {
-    match: createWrapMatcher("`+", BLOCK),
+    match: getWrapMatcher("`+", 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.")
@@ -219,7 +219,7 @@ const CODE = {
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
  */
 const STRONG = {
-    match: createWrapMatcher("\\*+"),
+    match: getWrapMatcher("\\*+"),
     render: ([, , children]) => ({ type: "strong", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -233,7 +233,7 @@ const STRONG = {
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
  */
 const EM = {
-    match: createWrapMatcher("_+"),
+    match: getWrapMatcher("_+"),
     render: ([, , children]) => ({ type: "em", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -247,7 +247,7 @@ const EM = {
  * - Markdown doesn't have this.
  */
 const INS = {
-    match: createWrapMatcher("\\++"),
+    match: getWrapMatcher("\\++"),
     render: ([, , children]) => ({ type: "ins", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -261,7 +261,7 @@ const INS = {
  * - Markdown doesn't have this.
  */
 const DEL = {
-    match: createWrapMatcher("~+"),
+    match: getWrapMatcher("~+"),
     render: ([, , children]) => ({ type: "del", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -275,7 +275,7 @@ const DEL = {
  *   - This works better with textareas that wrap text (since manually breaking up long lines is no longer necessary).
  */
 const BR = {
-    match: createMatcher(/\n/),
+    match: getMatcher(/\n/),
     render: () => ({ type: "br", key: null, props: {} }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.29.0",
+	"version": "1.30.3",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -63,20 +63,20 @@
 		"@types/jest": "^27.0.3",
 		"@types/react": "^17.0.37",
 		"@types/react-dom": "^17.0.11",
-		"@typescript-eslint/eslint-plugin": "^5.5.0",
-		"@typescript-eslint/parser": "^5.5.0",
-		"eslint": "^8.4.0",
+		"@typescript-eslint/eslint-plugin": "^5.6.0",
+		"@typescript-eslint/parser": "^5.6.0",
+		"eslint": "^8.4.1",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-import": "^2.25.3",
 		"eslint-plugin-prettier": "^4.0.0",
-		"firebase": "^9.6.0",
-		"jest": "^27.4.3",
+		"firebase": "^9.6.1",
+		"jest": "^27.4.4",
 		"jest-ts-webcompat-resolver": "^1.0.0",
 		"prettier": "^2.5.1",
 		"react": "^17.0.2",
 		"react-dom": "^17.0.2",
-		"ts-jest": "^27.0.7",
-		"typescript": "^4.5.2"
+		"ts-jest": "^27.1.1",
+		"typescript": "^4.5.3"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=4.0.0",

package/react/index.d.ts

@@ -7,4 +7,5 @@ export * from "./useFetch.js";
 export * from "./useDocument.js";
 export * from "./useDocumentData.js";
 export * from "./useQuery.js";
+export * from "./useQueryFirst.js";
 export * from "./usePagination.js";

package/react/index.js

@@ -7,4 +7,5 @@ export * from "./useFetch.js";
 export * from "./useDocument.js";
 export * from "./useDocumentData.js";
 export * from "./useQuery.js";
+export * from "./useQueryFirst.js";
 export * from "./usePagination.js";

package/react/useDocumentData.d.ts

@@ -14,7 +14,7 @@ import { DataDocument, Data } from "../index.js";
  * @trhows `Error` if a `CacheProvider` is not part of the database's provider chain.
  * @throws `Error` if there was a problem retrieving the data.
  */
-export declare function useAsyncDocumentData<T extends Data>(ref: DataDocument<T>, maxAge?: number | true): T | Promise<T>;
+export declare function useAsyncDocumentData<T extends Data>(ref: DataDocument<T>, maxAge?: number | true): T | PromiseLike<T>;
 export declare function useAsyncDocumentData<T extends Data>(ref: DataDocument<T> | undefined, maxAge?: number | true): T | PromiseLike<T> | undefined;
 /**
  * Use the cached data of a document in a React component.

package/react/useQueryFirst.d.ts

@@ -0,0 +1,36 @@
+import { DataQuery, Data, Entry } from "../index.js";
+/**
+ * Use the cached data of a document in a React component (or a `Promise` to indicate the data is still loading).
+ * - Requires database to use `CacheProvider` and will error if this does not exist.
+ *
+ * @param ref Query reference or `undefined`.
+ * - If `undefined` is set this function will always return `undefined` (this simplifies scenarios where no document is needed, as hooks must always be called in the same order).
+ * @param maxAge How 'out of date' data is allowed to be before it'll be refetched.
+ * - If `maxAge` is true, a realtime subscription to the data will be created for the lifetime of the component.
+ *
+ * @returns The data of the document, or `Promise` that resolves when the data has loaded.
+ *
+ * @throws `RequiredError` if the query had no results.
+ * @trhows `Error` if a `CacheProvider` is not part of the database's provider chain.
+ * @throws `Error` if there was a problem retrieving the data.
+ */
+export declare function useAsyncQueryFirst<T extends Data>(ref: DataQuery<T>, maxAge?: number | true): Entry<T> | PromiseLike<Entry<T>>;
+export declare function useAsyncQueryFirst<T extends Data>(ref: DataQuery<T> | undefined, maxAge?: number | true): Entry<T> | PromiseLike<Entry<T>> | undefined;
+/**
+ * Use the cached data of a document in a React component.
+ * - Requires database to use `CacheProvider` and will error if this does not exist.
+ *
+ * @param ref Query reference or `undefined`.
+ * - If `undefined` is set this function will always return `undefined` (this simplifies scenarios where no document is needed, as hooks must always be called in the same order).
+ * @param maxAge How 'out of date' data is allowed to be before it'll be refetched.
+ * - If `maxAge` is true, a realtime subscription to the data will be created for the lifetime of the component.
+ *
+ * @returns The data of the document.
+ *
+ * @throws `Promise` that resolves when the data has loaded.
+ * @throws `RequiredError` if the query had no results.
+ * @trhows `Error` if a `CacheProvider` is not part of the database's provider chain.
+ * @throws `Error` if there was a problem retrieving the data.
+ */
+export declare function useQueryFirst<T extends Data>(ref: DataQuery<T>, maxAge?: number | true): Entry<T>;
+export declare function useQueryFirst<T extends Data>(ref: DataQuery<T> | undefined, maxAge?: number | true): Entry<T> | undefined;

package/react/useQueryFirst.js

@@ -0,0 +1,9 @@
+import { callAsync, getQueryFirst, throwAsync } from "../index.js";
+import { useAsyncQuery } from "./useQuery.js";
+export function useAsyncQueryFirst(ref, maxAge) {
+    const results = useAsyncQuery(ref, maxAge);
+    return ref && results ? callAsync(getQueryFirst, results, ref) : undefined;
+}
+export function useQueryFirst(ref, maxAge) {
+    return throwAsync(useAsyncQueryFirst(ref, maxAge));
+}

package/schema/StringSchema.d.ts

@@ -1,6 +1,8 @@
 import { Schema } from "./Schema.js";
 /** `type=""` prop for HTML `<input />` tags that are relevant for strings. */
 export declare type HtmlInputType = "text" | "password" | "color" | "date" | "email" | "number" | "tel" | "search" | "url";
+/** Function that sanitizes a string. */
+export declare type Sanitizer = (str: string) => string;
 /**
  * Schema that defines a valid string.
  *
@@ -27,16 +29,16 @@ export declare class StringSchema extends Schema<string> {
     readonly min: number;
     readonly max: number | null;
     readonly match: RegExp | null;
+    readonly sanitizer: Sanitizer | null;
     readonly multiline: boolean;
-    readonly trim: boolean;
-    constructor({ value, type, min, max, match, multiline, trim, ...rest }: ConstructorParameters<typeof Schema>[0] & {
+    constructor({ value, type, min, max, match, sanitizer, multiline, ...rest }: ConstructorParameters<typeof Schema>[0] & {
         readonly value?: string;
         readonly type?: HtmlInputType;
         readonly min?: number;
         readonly max?: number | null;
         readonly match?: RegExp | null;
+        readonly sanitizer?: Sanitizer | null;
         readonly multiline?: boolean;
-        readonly trim?: boolean;
     });
     validate(unsafeValue?: unknown): string;
     /**

package/schema/StringSchema.js

@@ -22,15 +22,15 @@ import { Schema } from "./Schema.js";
  *  schema.validate('j'); // Throws 'Minimum 3 chaacters'
  */
 export class StringSchema extends Schema {
-    constructor({ value = "", type = "text", min = 0, max = null, match = null, multiline = false, trim = true, ...rest }) {
+    constructor({ value = "", type = "text", min = 0, max = null, match = null, sanitizer = null, multiline = false, ...rest }) {
         super(rest);
         this.type = type;
         this.value = value;
         this.min = min;
         this.max = max;
         this.match = match;
+        this.sanitizer = sanitizer;
         this.multiline = multiline;
-        this.trim = trim;
     }
     validate(unsafeValue = this.value) {
         const unsafeString = typeof unsafeValue === "number" ? unsafeValue.toString() : unsafeValue;
@@ -51,7 +51,7 @@ export class StringSchema extends Schema {
      * - Applies `options.sanitizer` too (if it's set).
      */
     sanitize(uncleanString) {
-        return this.multiline ? sanitizeLines(uncleanString, this.trim) : sanitizeString(uncleanString, this.trim);
+        return this.sanitizer ? this.sanitizer(uncleanString) : this.multiline ? sanitizeLines(uncleanString) : sanitizeString(uncleanString);
     }
 }
 /** Valid string, e.g. `Hello there!` */

package/stream/State.d.ts

@@ -1,5 +1,5 @@
 import { Transformer, LOADING, ObserverType, NOERROR, Observer } from "../util/index.js";
-import { Stream } from "./Stream.js";
+import { AnyStream, Stream } from "./Stream.js";
 /** Any state (useful for `extends AnySubscribable` clauses). */
 export declare type AnyState = State<any>;
 /**
@@ -14,8 +14,11 @@ export declare type AnyState = State<any>;
  * */
 export interface State<T> {
     to(): State<T>;
+    to<O extends AnyStream>(target: O): O;
     derive<TT>(transformer: Transformer<T, TT>): State<TT>;
+    derive<O extends AnyStream>(transformer: Transformer<T, ObserverType<O>>, target: O): O;
     deriveAsync<TT>(transformer: Transformer<T, PromiseLike<TT>>): State<TT>;
+    deriveAsync<O extends AnyStream>(transformer: Transformer<T, Promise<ObserverType<O>>>, target: O): O;
 }
 export declare class State<T> extends Stream<T> {
     static [Symbol.species]: typeof State;

package/util/data.d.ts

@@ -134,3 +134,11 @@ export declare type DeepMutable<T extends Data> = {
 export declare type DeepReadonly<T extends Data> = {
     +readonly [K in keyof T]: T[K] extends Data ? DeepReadonly<T[K]> : T[K];
 };
+/** Pick only the properties of an object that match a type. */
+export declare type PickProps<T, TT> = Pick<T, {
+    [K in keyof T]: T[K] extends TT ? K : never;
+}[keyof T]>;
+/** Omit the properties of an object that match a type. */
+export declare type OmitProps<T, TT> = Omit<T, {
+    [K in keyof T]: T[K] extends TT ? K : never;
+}[keyof T]>;

package/util/search.d.ts

@@ -36,7 +36,7 @@ export declare function MATCHES_ANY(item: unknown, regexps: ImmutableArray<RegEx
  * - Quoted phrases match fully (starting and ending with a word boundary).
  */
 export declare const toWordRegExps: (query: string) => ImmutableArray<RegExp>;
-/** Convert a string word to the corresponding set of case-insensitive regular expressions. */
+/** Convert a string to a regular expression matching the start of a word boundary. */
 export declare const toWordRegExp: (word: string) => RegExp;
 /** Matcher that matches any words in a string. */
 export declare class MatchAnyWord implements Matchable<unknown, void> {
@@ -51,7 +51,7 @@ export declare class MatchAllWords implements Matchable<unknown, void> {
     match(value: string): boolean;
 }
 /** Matcher that matches an exact phrase. */
-export declare class MatchPhrase implements Matchable<unknown, void> {
+export declare class MatchWord implements Matchable<unknown, void> {
     private _regexp;
     constructor(phrase: string);
     match(value: string): boolean;

package/util/search.js

@@ -50,9 +50,9 @@ export function MATCHES_ANY(item, regexps) {
  * - Unquoted words match partially (starting with a word boundary).
  * - Quoted phrases match fully (starting and ending with a word boundary).
  */
-export const toWordRegExps = (query) => toWords(query).map(normalizeString).map(toWordRegExp);
-/** Convert a string word to the corresponding set of case-insensitive regular expressions. */
-export const toWordRegExp = (word) => word.includes(" ") ? new RegExp(`\\b${escapeRegExp(word)}\\b`, "i") : new RegExp(`\\b${escapeRegExp(word)}`, "i");
+export const toWordRegExps = (query) => toWords(query).map(toWordRegExp);
+/** Convert a string to a regular expression matching the start of a word boundary. */
+export const toWordRegExp = (word) => new RegExp(`\\b${escapeRegExp(normalizeString(word))}`, "i");
 /** Matcher that matches any words in a string. */
 export class MatchAnyWord {
     constructor(words) {
@@ -72,7 +72,7 @@ export class MatchAllWords {
     }
 }
 /** Matcher that matches an exact phrase. */
-export class MatchPhrase {
+export class MatchWord {
     constructor(phrase) {
         this._regexp = toWordRegExp(phrase);
     }

package/util/string.d.ts

@@ -29,51 +29,53 @@ export declare function toTitle(value: unknown): string;
  * - Stripping control characters.
  * - Normalising all space characters to " " space.
  *
- * @param dirty The dirty input string.
+ * @param str The dirty input string.
  * @param multiline If `true`, `\t` horizontal tabs and `\r` newlines are allowed (defaults to `false` which strips these characters).
  * @returns The clean output string.
  */
-export declare function sanitizeString(dirty: string, trim?: boolean): string;
+export declare const sanitizeString: (str: string) => string;
 /**
  * Sanitize a multiline string.
  * - Like `sanitizeString()` but allows `\t` horizontal tab and `\r` newline.
  */
-export declare function sanitizeLines(dirty: string, trim?: boolean): string;
+export declare const sanitizeLines: (str: string) => string;
 /**
  * Normalize a string so it can be compared to another string (free from upper/lower cases, symbols, punctuation).
  *
  * Does the following:
- * - Santize the string to remove control characters.
+ * - Removes control characters.
  * - Remove symbols (e.g. `$` dollar) and punctuation (e.g. `"` double quote).
  * - Remove marks (e.g. the umlout dots above `ö`).
  * - Convert spaces/separators to " " single space (e.g. line breaks, non-breaking space).
  * - Convert to lowercase and trim excess whitespace.
  *
- * @example normalizeString("Däve-is REALLY éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
+ * @example normalizeString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
  */
-export declare const normalizeString: (value: string) => string;
+export declare const normalizeString: (str: string) => string;
 /**
  * Convert a string to a `kebab-case` URL slug.
  * - Remove any characters not in the range `[a-z0-9-]`
  * - Change all spaces/separators/hyphens/dashes/underscores to `-` single hyphen.
  */
-export declare const toSlug: (value: string) => string;
+export declare const toSlug: (str: string) => string;
 /**
  * Split a string into its separate words.
  * - Words enclosed "in quotes" are a single word.
  * - Performs no processing on the words, so control chars, punctuation, symbols, and case are all preserved.
  *
- * @param value The input string, e.g. `yellow dog   "Golden Retriever"`
+ * @param str The input string, e.g. `yellow dog   "Golden Retriever"`
  * @returns Array of the found words, e.g. `["yellow", "dog", "Golden Retriever"
  */
-export declare const toWords: (value: string) => ImmutableArray<string>;
+export declare const toWords: (str: string) => ImmutableArray<string>;
+/** Find and iterate over the words in a string. */
+export declare function yieldWords(value: string): Generator<string, void, void>;
 /**
  * Convert a string to a regular expression that matches that string.
  *
- * @param value The input string.
+ * @param str The input string.
  * @param flags RegExp flags that are passed into the created RegExp.
  */
-export declare const toRegExp: (value: string, flags?: string) => RegExp;
+export declare const toRegExp: (str: string, flags?: string) => RegExp;
 /** Escape special characters in a string regular expression. */
 export declare const escapeRegExp: (str: string) => string;
 /** Is the first character of a string an uppercase letter? */

package/util/string.js

@@ -3,7 +3,6 @@ import { formatDate } from "./date.js";
 import { isData } from "./data.js";
 import { isArray } from "./array.js";
 import { formatNumber, isBetween } from "./number.js";
-import { IS_DEFINED } from "./undefined.js";
 /** Is a value a string? */
 export const IS_STRING = (v) => typeof v === "string";
 /**
@@ -66,69 +65,70 @@ export function toTitle(value) {
  * - Stripping control characters.
  * - Normalising all space characters to " " space.
  *
- * @param dirty The dirty input string.
+ * @param str The dirty input string.
  * @param multiline If `true`, `\t` horizontal tabs and `\r` newlines are allowed (defaults to `false` which strips these characters).
  * @returns The clean output string.
  */
-export function sanitizeString(dirty, trim = true) {
-    const clean = dirty.replace(CONTROLS, "").replace(SPACES, " ");
-    return trim ? clean.trim() : clean;
-}
-const CONTROLS = /[\x00-\x1F\x7F-\x9F]/g; // All control characters (`\x00`-`\x1F`, `\x7F`-`\x9F`)
-const SPACES = /\s/g; // Sanitize zero-width spacers etc.
+export const sanitizeString = (str) => str.replace(SANE_SPACES, " ").replace(SANE_STRIP, "").trim();
+const SANE_SPACES = /\s+/g; // Runs of spaces.
+const SANE_STRIP = /[\x00-\x1F\x7F-\x9F]+/g; // Control characters.
 /**
  * Sanitize a multiline string.
  * - Like `sanitizeString()` but allows `\t` horizontal tab and `\r` newline.
  */
-export function sanitizeLines(dirty, trim = true) {
-    const clean = dirty.replace(CONTROLS_MULTILINE, "").replace(SPACES_MULTILINE, " ");
-    return trim ? clean.replace(TRIM_END_MULTILINE, "") : clean;
-}
-const CONTROLS_MULTILINE = /(?![\t\n])[\x00-\x1F\x7F-\x9F]/g; // Control characters except `\t` horizontal tab and `\n` new line.
-const SPACES_MULTILINE = /(?![\t\n])\s/g; // All spaces except `\t` horizontal tab and `\n` new line.
-const TRIM_END_MULTILINE = /\s+$/gm;
+export const sanitizeLines = (str) => str.replace("\u2029", "\n\n").replace(LINE_SPACES, " ").replace(LINE_STRIP, "").replace(LINE_ENDS, "").replace(LINE_START, "").replace(LINE_BREAKS, "\n\n");
+const LINE_SPACES = /[^\S \t\n]/g; // Spaces except tab and newline.
+const LINE_STRIP = /[\x00-\x08\x0B-\x1F\x7F-\x9F]+/g; // Control characters (except tab and newline).
+const LINE_ENDS = /[ \t]+$/gm; // Spaces and tabs at ends of lines.
+const LINE_START = /^\n+|\n+$/g; // Newlines at start and end of string.
+const LINE_BREAKS = /\n\n\n+/g; // Three or more linebreaks in a row.
 /**
  * Normalize a string so it can be compared to another string (free from upper/lower cases, symbols, punctuation).
  *
  * Does the following:
- * - Santize the string to remove control characters.
+ * - Removes control characters.
  * - Remove symbols (e.g. `$` dollar) and punctuation (e.g. `"` double quote).
  * - Remove marks (e.g. the umlout dots above `ö`).
  * - Convert spaces/separators to " " single space (e.g. line breaks, non-breaking space).
  * - Convert to lowercase and trim excess whitespace.
  *
- * @example normalizeString("Däve-is REALLY éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
+ * @example normalizeString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
  */
-export const normalizeString = (value) => sanitizeString(value).normalize("NFD").replace(STRIP, "").replace(SEPARATORS, " ").trim().toLowerCase();
-const STRIP = /[\p{Symbol}\p{Mark}\p{Punctuation}]+/gu;
-const SEPARATORS = /\s+/g;
+export const normalizeString = (str) => sanitizeString(str.normalize("NFD").replace(NORMAL_STRIP, "").toLowerCase());
+const NORMAL_STRIP = /[^\p{L}\p{N}\s]+/gu; // Anything except letters, numbers, spaces.
 /**
  * Convert a string to a `kebab-case` URL slug.
  * - Remove any characters not in the range `[a-z0-9-]`
  * - Change all spaces/separators/hyphens/dashes/underscores to `-` single hyphen.
  */
-export const toSlug = (value) => value.toLowerCase().normalize("NFD").replace(TO_HYPHEN, "-").replace(NON_ALPHANUMERIC, "").replace(TRIM_HYPHENS, "");
-const TO_HYPHEN = /[\s-–—_]+/g; // Anything that is a space becomes a hyphen.
-const NON_ALPHANUMERIC = /[^a-z0-9-]+/gu; // Anything that isn't [a-z0-9-] gets removed.
-const TRIM_HYPHENS = /^-+|-+$/g; // Trim excess hyphens at start and end.
+export const toSlug = (str) => str.toLowerCase().normalize("NFD").replace(SLUG_HYPHENS, "-").replace(SLUG_STRIP, "");
+const SLUG_HYPHENS = /[\s\-–—_]+/gu; // Runs of spaces and hyphens.
+const SLUG_STRIP = /^[^a-z0-9]+|[^a-z0-9]+$|[^a-z0-9-]+/g; // Non-alphanumeric or hyphen anywhere, or non-alphanumeric at start and end.
 /**
  * Split a string into its separate words.
  * - Words enclosed "in quotes" are a single word.
  * - Performs no processing on the words, so control chars, punctuation, symbols, and case are all preserved.
  *
- * @param value The input string, e.g. `yellow dog   "Golden Retriever"`
+ * @param str The input string, e.g. `yellow dog   "Golden Retriever"`
  * @returns Array of the found words, e.g. `["yellow", "dog", "Golden Retriever"
  */
-export const toWords = (value) => Array.from(value.matchAll(MATCH_WORD)).map(toWord).filter(IS_DEFINED);
-const toWord = (matches) => matches[1] || matches[0] || undefined;
-const MATCH_WORD = /[^\s"]+|"([^"]*)"/g;
+export const toWords = (str) => Array.from(yieldWords(str));
+/** Find and iterate over the words in a string. */
+export function* yieldWords(value) {
+    for (const matches of value.matchAll(MATCH_WORD)) {
+        const str = matches[1] || matches[0];
+        if (str)
+            yield str;
+    }
+}
+const MATCH_WORD = /[^\s"]+|"([^"]*)"/g; // Runs of characters without spaces, or "quoted phrases"
 /**
  * Convert a string to a regular expression that matches that string.
  *
- * @param value The input string.
+ * @param str The input string.
  * @param flags RegExp flags that are passed into the created RegExp.
  */
-export const toRegExp = (value, flags = "") => new RegExp(escapeRegExp(value), flags);
+export const toRegExp = (str, flags = "") => new RegExp(escapeRegExp(str), flags);
 /** Escape special characters in a string regular expression. */
 export const escapeRegExp = (str) => str.replace(REPLACE_ESCAPED, "\\$&");
 const REPLACE_ESCAPED = /[-[\]/{}()*+?.\\^$|]/g;