shelving 1.124.5 → 1.126.0

package/markup/regexp.d.ts

@@ -9,9 +9,6 @@ export type MarkupMatch<T extends Data | undefined> = {
 };
 /** Function that matches a string and returns a `MarkupMatch` or `null` or `void` */
 export type MarkupMatcher<T extends Data> = (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;
@@ -21,27 +18,21 @@ export declare function getBlockRegExp<T extends string>(content: `(?<${T}>${str
     [K in T]: string;
 }>;
 export declare function getBlockRegExp(content?: PossibleRegExp, end?: PossibleRegExp, start?: PossibleRegExp): RegExp;
+export declare const LINE_REGEXP: RegExp;
+export declare const LINE_START_REGEXP: RegExp;
+export declare const LINE_END_REGEXP: RegExp;
 /** Create regular expression that matches a line of content. */
 export declare function getLineRegExp<T extends NamedRegExpData>(content: NamedRegExp<T>): NamedRegExp<T>;
 export declare function getLineRegExp<T extends string>(content: `(?<${T}>${string})`): NamedRegExp<{
     [K in T]: string;
 }>;
 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, flags?: string);
-    exec(input: string): RegExpExecArray | null;
-    test(input: string): boolean;
-}
+export declare const WORD_REGEXP: RegExp;
+export declare const WORD_START_REGEXP: RegExp;
+export declare const WORD_END_REGEXP: RegExp;
+/** Create regular expression that matches a line of content. */
+export declare function getWordRegExp<T extends NamedRegExpData>(content: NamedRegExp<T>): NamedRegExp<T>;
+export declare function getWordRegExp<T extends string>(content: `(?<${T}>${string})`): NamedRegExp<{
+    [K in T]: string;
+}>;
+export declare function getWordRegExp(content?: PossibleRegExp, end?: PossibleRegExp, start?: PossibleRegExp): RegExp;

package/markup/regexp.js

@@ -1,47 +1,19 @@
 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).
+export const BLOCK_REGEXP = /[\s\S]*?/; // Block of content (shortest possible run of any character including newlines).
+export const BLOCK_START_REGEXP = /^\n*|\n+/; // Start of block (one or more linebreaks, or start of string).
+export const BLOCK_END_REGEXP = /\n*$|\n\n+/; // End of block (two or more linebreaks, or end of string).
 export function getBlockRegExp(content = BLOCK_REGEXP, end = BLOCK_END_REGEXP, start = BLOCK_START_REGEXP) {
     return new RegExp(`(?:${getRegExpSource(start)})(?:${getRegExpSource(content)})(?:${getRegExpSource(end)})`);
 }
+export const LINE_REGEXP = /[^\n]*/; // Line of content (anything that's not a newline).
+export const LINE_START_REGEXP = /^\n*|\n+/; // Start of line (one or more linebreaks, or start of string).
+export const LINE_END_REGEXP = /\n+|$/; // End of line (one or more linebreaks, or end of string).
 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, flags) {
-        super(`(?<lookbehind>^|[^\\p{L}\\p{N}])${pattern}(?![\\p{L}\\p{N}])`, flags);
-    }
-    exec(input) {
-        const match = super.exec(input);
-        if (match) {
-            const { 0: zero, groups } = match;
-            const offset = groups?.lookbehind?.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);
-    }
+export const WORD_REGEXP = /[\\p{L}\\p{N}]+/; // Match line of content (anything that's not a newline).
+export const WORD_START_REGEXP = /(?<![\\p{L}\\p{N}])/; // Start of word (previous character is not a letter or number).
+export const WORD_END_REGEXP = /(?![\\p{L}\\p{N}])/; // End of word (next character is not a letter or number).
+export function getWordRegExp(content = WORD_REGEXP, end = WORD_END_REGEXP, start = WORD_START_REGEXP) {
+    return new RegExp(`(?:${getRegExpSource(start)})(?:${getRegExpSource(content)})(?:${getRegExpSource(end)})`);
 }

package/markup/render.js

@@ -1,5 +1,6 @@
 /* eslint-disable no-param-reassign */
 import { isArray } from "../util/array.js";
+import { mapArray } from "../util/transform.js";
 import { MARKUP_OPTIONS } from "./options.js";
 /**
  * Parse a text string as Markdownish syntax and render it as a JSX node.
@@ -55,11 +56,8 @@ function _renderNode(node, options, context) {
         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;
-    }
+    if (isArray(node))
+        return mapArray(node, _renderNode, options, context);
     return _renderElement(node, options, context);
 }
 /**
@@ -108,7 +106,7 @@ function* _parseString(input, options, outerContext, offset = 0) {
         // 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 { index, length, context } = element;
-        element.key = offset + index;
+        element.key = (offset + index).toString();
         yield context ? _renderElement(element, options, context) : element;
         // Decrement the content.
         const suffix = input.slice(index + length);

package/markup/rules.d.ts

@@ -111,7 +111,6 @@ declare const INLINE_CHARS: {
 };
 export declare const INLINE_RULE: NamedRegExpMarkupRule<{
     char: keyof typeof INLINE_CHARS;
-    wrap: string;
     text: string;
 }>;
 /**

package/markup/rules.js

@@ -1,5 +1,5 @@
 import { getRegExp } from "../util/regexp.js";
-import { BLOCK_REGEXP, LINE_REGEXP, WordRegExp, getBlockRegExp, getLineRegExp } from "./regexp.js";
+import { BLOCK_REGEXP, LINE_REGEXP, getBlockRegExp, getLineRegExp, getWordRegExp } from "./regexp.js";
 import { LinkRegExpMarkupRule, NamedRegExpMarkupRule, RegExpMarkupRule } from "./rule.js";
 /** React security symbol — see https://github.com/facebook/react/pull/4832 */
 const $$typeof = Symbol.for("react.element");
@@ -51,7 +51,7 @@ export const UNORDERED_RULE = new NamedRegExpMarkupRule(getBlockRegExp(`(?<list>
 }), ["block", "list"]);
 const _mapUnordered = (item, key) => ({
     type: "li",
-    key,
+    key: key.toString(),
     ref: null,
     $$typeof,
     props: { children: item.replace(UNORDERED_INDENT, "") },
@@ -74,7 +74,7 @@ export const ORDERED_RULE = new NamedRegExpMarkupRule(getBlockRegExp(`(?<list>${
 }), ["block", "list"]);
 const _mapOrdered = (item, key) => ({
     type: "li",
-    key,
+    key: key.toString(),
     ref: null,
     $$typeof,
     props: {
@@ -195,7 +195,7 @@ export const CODE_RULE = new NamedRegExpMarkupRule(new RegExp(`(?<wrap>\`+)(?<co
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
  */
 const INLINE_CHARS = { "-": "del", "~": "del", "+": "ins", "*": "strong", "_": "em", "=": "mark", ":": "mark" }; // Hyphen must be first so it works when we use the keys as a character class.
-export const INLINE_RULE = new NamedRegExpMarkupRule(new WordRegExp(`(?<wrap>(?<char>[${Object.keys(INLINE_CHARS).join("")}])+)(?<text>(?!\\k<char>)\\S|(?!\\k<char>)\\S[\\s\\S]*?(?!\\k<char>)\\S)\\k<wrap>`), // prettier-ignore
+export const INLINE_RULE = new NamedRegExpMarkupRule(getWordRegExp(`(?<wrap>(?<char>[${Object.keys(INLINE_CHARS).join("")}])+)(?<text>(?!\\k<char>)\\S(?:[\\s\\S]*?(?!\\k<char>)\\S)?)\\k<wrap>`), // prettier-ignore
 ({ char, text }) => ({
     type: INLINE_CHARS[char],
     key: null,

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.124.5",
+	"version": "1.126.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -60,13 +60,13 @@
 		"build:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config=jest.config.build.cjs"
 	},
 	"devDependencies": {
-		"@google-cloud/firestore": "^6.4.2",
+		"@google-cloud/firestore": "^7.3.0",
 		"@types/jest": "^29.4.0",
 		"@types/react": "^18.0.27",
 		"@types/react-dom": "^18.0.10",
-		"@typescript-eslint/eslint-plugin": "^6.7.0",
-		"@typescript-eslint/parser": "^6.7.0",
-		"esbuild": "^0.19.2",
+		"@typescript-eslint/eslint-plugin": "^7.1.0",
+		"@typescript-eslint/parser": "^7.1.0",
+		"esbuild": "^0.20.1",
 		"esbuild-jest": "^0.5.0",
 		"eslint": "^8.33.0",
 		"eslint-config-prettier": "^9.0.0",

package/schema/PhoneSchema.js

@@ -16,7 +16,7 @@ export class PhoneSchema extends StringSchema {
             ...options,
             type: "tel",
             min: 1,
-            max: 16,
+            max: 16, // Valid phone number is 16 digits or fewer (15 numerals with a leading `+` plus).
             match: PHONE_REGEXP,
             multiline: false,
         });

package/util/async.js

@@ -71,7 +71,7 @@ export function getDeferred() {
             resolve = x;
             reject = y;
         }),
-        resolve: resolve,
+        resolve: resolve, // eslint-disable-line @typescript-eslint/no-non-null-assertion
         reject: reject, // eslint-disable-line @typescript-eslint/no-non-null-assertion
     };
 }

package/util/equal.d.ts

@@ -1,6 +1,6 @@
 import type { ImmutableArray } from "./array.js";
+import type { Match } from "./filter.js";
 import type { ImmutableMap } from "./map.js";
-import type { Match } from "./match.js";
 import type { ImmutableObject } from "./object.js";
 /** Is unknown value `left` exactly equal to `right`? */
 export declare function isEqual<T>(left: unknown, right: T): left is T;

package/util/index.d.ts

@@ -18,6 +18,7 @@ export * from "./entry.js";
 export * from "./equal.js";
 export * from "./error.js";
 export * from "./file.js";
+export * from "./filter.js";
 export * from "./focus.js";
 export * from "./function.js";
 export * from "./hash.js";
@@ -28,7 +29,6 @@ export * from "./jsx.js";
 export * from "./lazy.js";
 export * from "./link.js";
 export * from "./map.js";
-export * from "./match.js";
 export * from "./merge.js";
 export * from "./null.js";
 export * from "./number.js";

package/util/index.js

@@ -18,6 +18,7 @@ export * from "./entry.js";
 export * from "./equal.js";
 export * from "./error.js";
 export * from "./file.js";
+export * from "./filter.js";
 export * from "./focus.js";
 export * from "./function.js";
 export * from "./hash.js";
@@ -28,7 +29,6 @@ export * from "./jsx.js";
 export * from "./lazy.js";
 export * from "./link.js";
 export * from "./map.js";
-export * from "./match.js";
 export * from "./merge.js";
 export * from "./null.js";
 export * from "./number.js";

package/util/jsx.d.ts

@@ -1,18 +1,18 @@
 /** Set of valid props for a JSX element. */
-export type JSXProps = {
+export interface JSXProps {
     [key: string]: unknown;
     children?: JSXNode;
-};
+}
 /** JSX element (similar to `React.ReactElement`)  */
-export type JSXElement<P extends JSXProps = JSXProps> = {
-    type: string | ((props: P) => JSXElement | null);
+export interface JSXElement<P extends JSXProps = JSXProps> {
+    type: string | ((props: P) => JSXNode | null);
     props: P;
-    key: string | number | null;
+    key: string | null;
     ref?: null;
     $$typeof?: symbol;
-};
+}
 /** JSX node (similar to `React.ReactNode`) */
-export type JSXNode = undefined | null | string | JSXElement | JSXNode[];
+export type JSXNode = undefined | null | string | JSXElement | readonly JSXNode[];
 /** Is an unknown value a JSX element? */
 export declare function isJSXElement(value: unknown): value is JSXElement;
 /** Is an unknown value a JSX node? */

package/util/number.d.ts

@@ -24,6 +24,7 @@ export declare function assertMin(value: unknown, min: number): asserts value is
  *
  * Conversion rules:
  * - Finite numbers return numbers.
+ * - `-0` is normalised to `0`
  * - Strings are parsed as numbers.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`

package/util/number.js

@@ -43,13 +43,14 @@ export function assertMin(value, min) {
  *
  * Conversion rules:
  * - Finite numbers return numbers.
+ * - `-0` is normalised to `0`
  * - Strings are parsed as numbers.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`
  */
 export function getOptionalNumber(value) {
     if (typeof value === "number" && Number.isFinite(value))
-        return value === 0 ? 0 : value; // Convert `-0` to `0`
+        return value === 0 ? 0 : value;
     else if (typeof value === "string")
         return getOptionalNumber(parseFloat(value.replace(NOT_NUMERIC_REGEXP, "")));
     else if (value instanceof Date)

package/util/regexp.d.ts

@@ -22,15 +22,11 @@ export declare function escapeRegExp(pattern: string): string;
 export declare function getAnyRegExp(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
 /** Create regular expression that matches all of a list of other expressions. */
 export declare function getAllRegExp(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
-/** Match function for finding strings that match against regular expressions (use with `filter()` to positively filter iterable sets of items). */
-export declare function isRegExpMatch(item: string, target: RegExp): boolean;
-/** Match function for finding strings that match against regular expressions (use with `filter()` to negatively filter iterable sets of items). */
-export declare function notRegExpMatch(item: string, target: RegExp): boolean;
-/** Regular expression match array that you've asserted contains the specified named groups. */
+/** Regular expression match array that matches a specific string format. */
 export interface TypedRegExpExecArray<T extends string = string> extends RegExpExecArray {
     0: T;
 }
-/** Regular expression that you've asserted contains the specified named capture groups. */
+/** Regular expression that matches a specific string format. */
 export interface TypedRegExp<T extends string = string> extends RegExp {
     exec(input: string): TypedRegExpExecArray<T> | null;
 }
@@ -38,11 +34,29 @@ export interface TypedRegExp<T extends string = string> extends RegExp {
 export type NamedRegExpData = {
     [named: string]: string;
 };
-/** Regular expression match array that you've asserted contains the specified named groups. */
+/** Regular expression match array that contains the specified named groups. */
 export interface NamedRegExpExecArray<T extends NamedRegExpData = NamedRegExpData> extends RegExpExecArray {
     groups: T;
 }
-/** Regular expression that you've asserted contains the specified named capture groups. */
+/** Regular expression that contains the specified named capture groups. */
 export interface NamedRegExp<T extends NamedRegExpData = NamedRegExpData> extends RegExp {
     exec(input: string): NamedRegExpExecArray<T> | null;
 }
+/** Match function for finding strings that match against regular expressions (use with `filter()` to positively filter iterable sets of items). */
+export declare function isMatch(str: string, regexp: RegExp): boolean;
+/** Match function for finding strings that match against regular expressions (use with `filter()` to negatively filter iterable sets of items). */
+export declare function notMatch(str: string, regexp: RegExp): boolean;
+/** Get an optional regular expression match, or `undefined` if no match could be made. */
+export declare function getOptionalMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T> | undefined;
+export declare function getOptionalMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T> | undefined;
+export declare function getOptionalMatch(str: string, regexp: RegExp): RegExpExecArray | undefined;
+/** Get a required regular expression match, or throw `ValueError` if no match could be made. */
+export declare function getMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T>;
+export declare function getMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T>;
+export declare function getMatch(str: string, regexp: RegExp): RegExpExecArray;
+/** Get an optional regular expression match, or `undefined` if no match could be made. */
+export declare function getOptionalMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T | undefined;
+export declare function getOptionalMatchGroups(str: string, regexp: RegExp): NamedRegExpData | undefined;
+/** Get a required regular expression match, or throw `ValueError` if no match could be made. */
+export declare function getMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T;
+export declare function getMatchGroups(str: string, regexp: RegExp): NamedRegExpData;

package/util/regexp.js

@@ -44,10 +44,28 @@ export function getAllRegExp(patterns, flags) {
     return new RegExp(`^(?=.*?(?:${getArray(patterns).map(getRegExpSource).join("))(?=.*?(?:")}))`, flags);
 }
 /** Match function for finding strings that match against regular expressions (use with `filter()` to positively filter iterable sets of items). */
-export function isRegExpMatch(item, target) {
-    return target.test(item);
+export function isMatch(str, regexp) {
+    return regexp.test(str);
 }
 /** Match function for finding strings that match against regular expressions (use with `filter()` to negatively filter iterable sets of items). */
-export function notRegExpMatch(item, target) {
-    return !target.test(item);
+export function notMatch(str, regexp) {
+    return !regexp.test(str);
+}
+export function getOptionalMatch(str, regexp) {
+    return regexp.exec(str) || undefined;
+}
+export function getMatch(str, regexp) {
+    const match = getOptionalMatch(str, regexp);
+    if (!match)
+        throw new ValueError("Must match regular expression", str);
+    return match;
+}
+export function getOptionalMatchGroups(str, regexp) {
+    return regexp.exec(str)?.groups || undefined;
+}
+export function getMatchGroups(str, regexp) {
+    const groups = getOptionalMatchGroups(str, regexp);
+    if (!groups)
+        throw new ValueError("Must match regular expression", str);
+    return groups;
 }