shelving 1.69.1 → 1.71.1

package/api/Resource.js

@@ -1,6 +1,6 @@
 import { validate } from "../util/validate.js";
 import { getUndefined } from "../util/undefined.js";
-import { Feedback } from "../feedback/Feedback.js";
+import { isFeedback } from "../feedback/Feedback.js";
 import { ValidationError } from "../error/ValidationError.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions..
@@ -34,7 +34,7 @@ export class Resource {
             return validate(unsafeResult, this.result);
         }
         catch (thrown) {
-            throw thrown instanceof Feedback ? new ValidationError(`Invalid result for resource`, thrown) : thrown;
+            throw isFeedback(thrown) ? new ValidationError(`Invalid result for resource`, thrown) : thrown;
         }
     }
 }

package/error/ValidationError.js

@@ -1,7 +1,8 @@
+import { debug } from "../util/debug.js";
 /** Thrown if a value isn't valid. */
 export class ValidationError extends Error {
     constructor(message, feedback) {
-        super(`${message}:\n${feedback.toString()}`);
+        super(`${message}:\n${feedback.message} (received ${debug(feedback.details)})`);
         this.feedback = feedback;
     }
 }

package/feedback/Feedback.d.ts

@@ -12,28 +12,16 @@ import type { ImmutableObject } from "../util/object.js";
  */
 export declare class Feedback {
     /** String feedback message that is safe to show to a user. */
-    readonly feedback: string;
+    readonly message: string;
     /** Nested details providing deeper feedback. */
     readonly details: ImmutableObject;
     constructor(feedback: string, details?: ImmutableObject);
     /**
      * Map details to a set of string messages.
-     * - If a detail is another `Feedback` instance, return its feedback string.
+     * - If a detail is another `Feedback` instance, return its `.message` string.
      * - If a detail is anything else, convert it to string using `toString()`
      */
     get messages(): ImmutableObject<string>;
-    /**
-     * Convert to string (equivalent to `message.details`).
-     * Returns a string including the main message string and a deeply nested list of child message strings.
-     *
-     * > Invalid format
-     * > - name: Invalid format
-     * >   - first: Must be string
-     * >     - value: 123
-     * >   - last: Must be string
-     * >     - value: true
-     * > - age: Must be number
-     * >   - value: "abc"
-     */
-    toString(): string;
 }
+/** Is an unknown value a `Feedback` instance? */
+export declare const isFeedback: <T extends Feedback>(v: unknown) => v is Feedback;

package/feedback/Feedback.js

@@ -1,5 +1,5 @@
-import { debug } from "../util/debug.js";
-import { getTitle } from "../util/string.js";
+import { getString } from "../util/string.js";
+import { mapObject } from "../util/transform.js";
 /**
  * The `Feedback` class represents a feedback message that should be shown to the user.
  * - Basic `Feedback` is neither good nor bad, `SuccessFeedback` indicates good news, and `ErrorFeedback` indicates bad news.
@@ -13,41 +13,18 @@ import { getTitle } from "../util/string.js";
  */
 export class Feedback {
     constructor(feedback, details = {}) {
-        this.feedback = feedback;
+        this.message = feedback;
         this.details = details;
     }
     /**
      * Map details to a set of string messages.
-     * - If a detail is another `Feedback` instance, return its feedback string.
+     * - If a detail is another `Feedback` instance, return its `.message` string.
      * - If a detail is anything else, convert it to string using `toString()`
      */
     get messages() {
-        const messages = {};
-        for (const [k, v] of Object.entries(this.details)) {
-            if (v instanceof Feedback)
-                messages[k] = v.feedback;
-            else
-                messages[k] = getTitle(v);
-        }
-        return messages;
-    }
-    /**
-     * Convert to string (equivalent to `message.details`).
-     * Returns a string including the main message string and a deeply nested list of child message strings.
-     *
-     * > Invalid format
-     * > - name: Invalid format
-     * >   - first: Must be string
-     * >     - value: 123
-     * >   - last: Must be string
-     * >     - value: true
-     * > - age: Must be number
-     * >   - value: "abc"
-     */
-    toString() {
-        let output = this.feedback;
-        for (const [k, v] of Object.entries(this.details))
-            output += `\n- ${k}: ${v instanceof Feedback ? v.toString().replace(/\n/g, "\n  ") : debug(v)}`;
-        return output;
+        return mapObject(this.details, _getMessage);
     }
 }
+const _getMessage = (v) => (isFeedback(v) ? v.message : getString(v));
+/** Is an unknown value a `Feedback` instance? */
+export const isFeedback = (v) => v instanceof Feedback;

package/markup/index.d.ts

@@ -1,3 +1,4 @@
-export * from "./types.js";
+export * from "./options.js";
 export * from "./rules.js";
 export * from "./render.js";
+export * from "./regexp.js";

package/markup/index.js

@@ -1,3 +1,4 @@
-export * from "./types.js";
+export * from "./options.js";
 export * from "./rules.js";
 export * from "./render.js";
+export * from "./regexp.js";

package/markup/options.d.ts

@@ -0,0 +1,16 @@
+import { MarkupRules } from "./rules.js";
+/** The current parsing options (represents the current state of the parsing). */
+export declare type MarkupOptions = {
+    /** The active list of parsing rules. */
+    readonly rules: MarkupRules;
+    /** The initial context to start parsing in (rules may render their children with a different context). */
+    readonly context: string;
+    /** Set the base URL that any relative links will be relative to (defaults to `window.location.href`, if undefined then relative links won't work). */
+    readonly url: string | undefined;
+    /** Set the `rel=""` property used for any links (e.g. `rel="nofollow ugc"`). */
+    readonly rel: string | undefined;
+    /** Valid URL schemes/protocols for links (including trailing commas), defaults to `[`http:`, `https:`]` */
+    readonly schemes: string[];
+};
+/** Default options */
+export declare const MARKUP_OPTIONS: MarkupOptions;

package/markup/options.js

@@ -0,0 +1,9 @@
+import { MARKUP_RULES } from "./rules.js";
+/** Default options */
+export const MARKUP_OPTIONS = {
+    context: "block",
+    rules: MARKUP_RULES,
+    url: undefined,
+    rel: undefined,
+    schemes: ["http:", "https:"],
+};

package/markup/regexp.d.ts

@@ -0,0 +1,39 @@
+import type { Data } from "../util/data.js";
+import { PossibleRegExp } from "../util/regexp.js";
+import type { MarkupOptions } from "./options.js";
+/** Subset of `NamedRegExpArray<T>` that are the only things we're required return from a `MarkupMatcher` function. */
+export declare type MarkupMatch<T extends Data | undefined = Data | undefined> = {
+    0: string;
+    index: number;
+    groups: T;
+};
+/** Function that matches a string and returns a `MarkupMatch` or `null` or `void` */
+export declare type MarkupMatcher<T extends Data | undefined = Data | undefined> = (input: string, options: MarkupOptions) => MarkupMatch<T> | null | void;
+export declare const LINE_REGEXP: RegExp;
+export declare const LINE_START_REGEXP: RegExp;
+export declare const LINE_END_REGEXP: RegExp;
+export declare const BLOCK_REGEXP: RegExp;
+export declare const BLOCK_START_REGEXP: RegExp;
+export declare const BLOCK_END_REGEXP: RegExp;
+/** Create regular expression that matches a block of content. */
+export declare function getBlockRegExp(content?: PossibleRegExp, end?: PossibleRegExp, start?: PossibleRegExp): RegExp;
+/** Create regular expression that matches a line of content. */
+export declare function getLineRegExp(content?: PossibleRegExp, end?: PossibleRegExp, start?: PossibleRegExp): RegExp;
+/**
+ * Regular expression that only matches complete its pattern if it's a complete word.
+ * - Won't match if there are letters or numbers directly before/after the matched content.
+ * - Will match if there is punctuation before/after the matched content or it is at the start/end of the string.
+ * - e.g. `this` and `"this"` and `that this that` and `that (this) that` will match because `this` is a complete word.
+ * - e.g. `thatthis` and `thatthisthat` will not because `this` is only part of a complete word.
+ *
+ * @note This isn't guaranteed to work with `String.prototype.match()` and `String.prototype.replace()`
+ *
+ * @todo This can be much less complicated when Safari supports lookbehinds in regular expressions.
+ * - We use a negative lookahead for the end of the word and it works great.
+ * - If we could use a negative lookbehind for the start of the word we wouldn't need to create a function that offsets the start.
+ */
+export declare class WordRegExp extends RegExp {
+    constructor(pattern: string);
+    exec(input: string): RegExpExecArray | null;
+    test(input: string): boolean;
+}

package/markup/regexp.js

@@ -0,0 +1,50 @@
+import { getRegExpSource } from "../util/regexp.js";
+// Regular expressions.
+export const LINE_REGEXP = /[^\n]*/; // Match line of content (anything that's not a newline).
+export const LINE_START_REGEXP = /^\n*|\n+/; // Starts at start of line (one or more linebreak or start of string).
+export const LINE_END_REGEXP = /\n+|$/; // Ends at end of line (one or more linebreak or end of string).
+export const BLOCK_REGEXP = /[\s\S]*?/; // Match block of content (including newlines so don't be greedy).
+export const BLOCK_START_REGEXP = /^\n*|\n+/; // Starts at start of a block (one or more linebreak or start of string).
+export const BLOCK_END_REGEXP = /\n*$|\n\n+/; // End of a block (two or more linebreaks or end of string).
+/** Create regular expression that matches a block of content. */
+export function getBlockRegExp(content = BLOCK_REGEXP, end = BLOCK_END_REGEXP, start = BLOCK_START_REGEXP) {
+    return new RegExp(`(?:${getRegExpSource(start)})(?:${getRegExpSource(content)})(?:${getRegExpSource(end)})`);
+}
+/** Create regular expression that matches a line of content. */
+export function getLineRegExp(content = LINE_REGEXP, end = LINE_END_REGEXP, start = LINE_START_REGEXP) {
+    return new RegExp(`(?:${getRegExpSource(start)})(?:${getRegExpSource(content)})(?:${getRegExpSource(end)})`);
+}
+/**
+ * Regular expression that only matches complete its pattern if it's a complete word.
+ * - Won't match if there are letters or numbers directly before/after the matched content.
+ * - Will match if there is punctuation before/after the matched content or it is at the start/end of the string.
+ * - e.g. `this` and `"this"` and `that this that` and `that (this) that` will match because `this` is a complete word.
+ * - e.g. `thatthis` and `thatthisthat` will not because `this` is only part of a complete word.
+ *
+ * @note This isn't guaranteed to work with `String.prototype.match()` and `String.prototype.replace()`
+ *
+ * @todo This can be much less complicated when Safari supports lookbehinds in regular expressions.
+ * - We use a negative lookahead for the end of the word and it works great.
+ * - If we could use a negative lookbehind for the start of the word we wouldn't need to create a function that offsets the start.
+ */
+export class WordRegExp extends RegExp {
+    constructor(pattern) {
+        super(`(?<lookbehind>^|[^\\p{L}\\p{N}])${pattern}(?![\\p{L}\\p{N}])`);
+    }
+    exec(input) {
+        var _a;
+        const match = super.exec(input);
+        if (match) {
+            const { 0: zero, groups } = match;
+            const offset = ((_a = groups === null || groups === void 0 ? void 0 : groups.lookbehind) === null || _a === void 0 ? void 0 : _a.length) || 0;
+            if (zero && offset) {
+                match[0] = zero.slice(offset); // Slice off the start of the match to remove the matched first character.
+                match.index += offset; // Increment the index to remove the matched first character.
+            }
+        }
+        return match;
+    }
+    test(input) {
+        return !!this.exec(input);
+    }
+}

package/markup/render.d.ts

@@ -1,5 +1,5 @@
 import type { JSXNode } from "../util/jsx.js";
-import type { MarkupOptions } from "./types.js";
+import { MarkupOptions } from "./options.js";
 /**
  * Parse a text string as Markdownish syntax and render it as a JSX node.
  * - Syntax is not defined by this code, but by the rules supplied to it.
@@ -28,9 +28,9 @@ import type { MarkupOptions } from "./types.js";
  *           - If the first thing in the definition is a URL, then it's recognised as a link reference (and produces an `<a href=""></a>`)
  *           - If the first thing in the definition isn't a URL, then it's recognised as a sidenote/footnote and tapping it will scroll you to that point (and popup the definition like Marco Arment's Bigfoot code).
  *
- * @param content The string content possibly containing markup syntax, e.g. "This is a *bold* string.
+ * @param input The string content possibly containing markup syntax, e.g. "This is a *bold* string.
  * @param options An options object for the render.
  *
- * @returns ReactNode, i.e. either a complete `ReactElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
+ * @returns JSXNode, i.e. either a complete `JSXElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
  */
-export declare function renderMarkup(content: string, options?: Partial<MarkupOptions>): JSXNode;
+export declare function renderMarkup(input: string, options?: Partial<MarkupOptions>): JSXNode;

package/markup/render.js

@@ -1,116 +1,6 @@
 /* eslint-disable no-param-reassign */
-import { sanitizeLines } from "../util/string.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.
-    if (!options.context)
-        return content;
-    const nodes = [];
-    // Loop until we've parsed the entire string.
-    while (content.length) {
-        // Loop through all rules in the list and see if any match.
-        let matchedPriority = Number.MIN_SAFE_INTEGER;
-        let matchedIndex = Number.MAX_SAFE_INTEGER;
-        let matchedRule = undefined;
-        let matchedResult = undefined;
-        for (const rule of options.rules) {
-            const { priority = 0, match, regexp, contexts } = rule;
-            // Only apply this rule if both:
-            // 1. The priority is equal or higher to the current priority.
-            // 2. The rule is allowed in the current context.
-            if (priority >= matchedPriority && contexts.includes(options.context)) {
-                const result = match ? match(content, options) : regexp ? content.match(regexp) : null;
-                // If this matched and has an index (it might not if it's a `/g` global RegExp, which would be a mistake).
-                if (result && typeof result.index === "number") {
-                    const index = result.index;
-                    // Only match the rule if either:
-                    // 1. The index is lower than the previous index then this rule takes priority.
-                    // 2. The priority is higher than the previous match then this rule takes priority.
-                    if (index < matchedIndex || priority > matchedPriority) {
-                        matchedRule = rule;
-                        matchedResult = result;
-                        matchedIndex = index;
-                        matchedPriority = priority;
-                    }
-                }
-            }
-        }
-        // Did at least one rule match?
-        if (matchedRule && matchedResult && matchedResult[0]) {
-            // If index is more than zero, then add a string node before this one.
-            if (matchedIndex) {
-                const prefix = content.slice(0, matchedIndex);
-                appendNode(nodes, renderString(prefix, options));
-            }
-            // Call the rule's `render()` function to generate the node.
-            const childOptions = { ...options, context: matchedRule.childContext };
-            const element = matchedRule.render(matchedResult, childOptions);
-            appendNode(nodes, renderNode(element, childOptions));
-            // Decrement the content.
-            content = content.slice(matchedIndex + matchedResult[0].length);
-        }
-        else {
-            // If nothing else matched add the rest of the string as a node.
-            // Don't need to push the string through `renderNode()` because we already know it doesn't match any rules in the current context.
-            nodes.push(content);
-            content = "";
-        }
-    }
-    // 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).
- */
-function appendNode(nodes, node) {
-    if (!node) {
-        // No need to append null, undefined, or empty string.
-        return;
-    }
-    else if (typeof node === "string") {
-        // String nodes should be merged into the last node (if there are several in a row).
-        const i = nodes.length - 1;
-        if (typeof nodes[i] === "string")
-            nodes[i] += node;
-        else
-            nodes.push(node);
-    }
-    else if (node instanceof Array) {
-        // Nested arrays of nodes are flattened.
-        for (const n of node)
-            appendNode(nodes, n);
-    }
-    else {
-        // Generate `key` property using a numeric incrementor (if it's a string let it pass — there's probably a reason it's a string).
-        if (typeof node.key !== "string")
-            node.key = nodes.length;
-        // Append the node.
-        nodes.push(node);
-    }
-}
-/**
- * Render a JSX node
- * - Recursively renders the children of the node using the current options.
- */
-function renderNode(node, options) {
-    if (typeof node === "string")
-        return renderString(node, options);
-    if (node instanceof Array)
-        return node.map(n => renderNode(n, options));
-    if (typeof node === "object" && node) {
-        return {
-            ...node,
-            $$typeof: REACT_SECURITY_SYMBOL,
-            props: node.props.children ? { ...node.props, children: renderNode(node.props.children, options) } : node.props,
-        };
-    }
-    return node;
-}
-const REACT_SECURITY_SYMBOL = Symbol.for("react.element");
+import { isArray } from "../util/array.js";
+import { MARKUP_OPTIONS } from "./options.js";
 /**
  * Parse a text string as Markdownish syntax and render it as a JSX node.
  * - Syntax is not defined by this code, but by the rules supplied to it.
@@ -139,18 +29,100 @@ const REACT_SECURITY_SYMBOL = Symbol.for("react.element");
  *           - If the first thing in the definition is a URL, then it's recognised as a link reference (and produces an `<a href=""></a>`)
  *           - If the first thing in the definition isn't a URL, then it's recognised as a sidenote/footnote and tapping it will scroll you to that point (and popup the definition like Marco Arment's Bigfoot code).
  *
- * @param content The string content possibly containing markup syntax, e.g. "This is a *bold* string.
+ * @param input The string content possibly containing markup syntax, e.g. "This is a *bold* string.
  * @param options An options object for the render.
  *
- * @returns ReactNode, i.e. either a complete `ReactElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
+ * @returns JSXNode, i.e. either a complete `JSXElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
  */
-export function renderMarkup(content, options) {
-    return renderString(sanitizeLines(content), { ...defaults, ...options });
+export function renderMarkup(input, options) {
+    if (!input)
+        return null;
+    const combined = options ? { ...MARKUP_OPTIONS, ...options } : MARKUP_OPTIONS;
+    return _renderString(input, combined, combined.context);
+}
+/**
+ * Render a string to its corresponding JSX node in a given context.
+ */
+function _renderString(input, options, context) {
+    const nodes = Array.from(_parseString(input, options, context));
+    return !nodes.length ? null : nodes.length === 1 ? nodes[0] : nodes;
+}
+/**
+ * Render a JSX node in a given context.
+ */
+function _renderNode(node, options, context) {
+    if (!node)
+        return node;
+    if (typeof node === "string")
+        return _renderString(node, options, context);
+    if (isArray(node)) {
+        for (let i = 0; i <= node.length - 1; i++)
+            node[i] = _renderNode(node[i], options, context);
+        return node;
+    }
+    return _renderElement(node, options, context);
+}
+/**
+ * Render a JSX element in a given context.
+ */
+function _renderElement(element, options, context) {
+    if (element.props.children)
+        element.props.children = _renderNode(element.props.children, options, context);
+    return element;
+}
+/**
+ * Parse a string to its corresponding JSX nodes in a given context.
+ *
+ * @param offset Keeps track of where we are within the wider string we're parsing when we're several calls deep.
+ */
+function* _parseString(input, options, context, offset = 0) {
+    let matchedRule = undefined;
+    let matchedPriority = Number.MIN_SAFE_INTEGER;
+    let matchedIndex = Number.MIN_SAFE_INTEGER;
+    let matchedLength = 0;
+    let matchedGroups = undefined;
+    // Loop through all rules in the list and see if any match.
+    for (const rule of options.rules) {
+        // Only apply this rule if both:
+        // 1. The priority is equal or higher to the current priority.
+        // 2. The rule is allowed in the current context.
+        const { priority = 0, match, contexts } = rule;
+        if (priority >= matchedPriority && contexts.includes(context)) {
+            const result = typeof match === "function" ? match(input, options) : match.exec(input);
+            if (result) {
+                // Use the match if it has length and is earlier in the string or is higher priority.
+                const { 0: { length } = "", index, groups } = result;
+                if (length && (index < matchedIndex || priority > matchedPriority)) {
+                    matchedRule = rule;
+                    matchedPriority = priority;
+                    matchedIndex = index;
+                    matchedLength = length;
+                    matchedGroups = groups;
+                }
+            }
+        }
+    }
+    // Did at least one rule match?
+    if (matchedRule && matchedLength) {
+        // If index is more than zero, then the string before the match may match another rule at lower priority.
+        const prefix = input.slice(0, matchedIndex);
+        if (prefix.length)
+            yield* _parseString(prefix, options, context, offset);
+        // Call the rule's `render()` function to generate the node.
+        // React gets annoyed if we don't set a `key:` property on lists of elements.
+        // We use the string offset as the `.key` property in the element because it's cheap to calculate and guaranteed to be unique within the string.
+        // Trying to generate an incrementing number would require tracking the number and passing it back and forth through `_parseString()`
+        const { render, subcontext } = matchedRule;
+        const element = render(matchedGroups, options);
+        element.key = offset + matchedIndex;
+        yield subcontext ? _renderElement(element, options, subcontext) : element;
+        // Decrement the content.
+        const suffix = input.slice(matchedIndex + matchedLength);
+        if (suffix.length)
+            yield* _parseString(suffix, options, context, offset + matchedIndex + matchedLength);
+    }
+    else {
+        // If nothing matched return the entire string..
+        yield input;
+    }
 }
-const defaults = {
-    rules: MARKUP_RULES,
-    context: "block",
-    url: undefined,
-    rel: undefined,
-    schemes: ["http:", "https:"],
-};