shelving 1.124.5 → 1.125.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.124.5",
+	"version": "1.125.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

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/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;
 }