shelving 1.89.0 → 1.89.1

package/package.json

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

package/util/string.d.ts

@@ -32,7 +32,7 @@ export declare const isStringLength: (str: string, min?: number, max?: number) =
 /** Assert that a value has a specific length (or length is in a specific range). */
 export declare function assertStringLength(str: string | unknown, min?: number, max?: number): asserts str is string;
 /** Get a string if it has the specified minimum length.  */
-export declare function getStringLength(arr: string, min?: number, max?: number): string;
+export declare function getStringLength(str: string, min?: number, max?: number): string;
 /** Concatenate an iterable set of strings together. */
 export declare const joinStrings: (strs: Iterable<string> & NotString, joiner?: string) => string;
 /**
@@ -63,16 +63,17 @@ export declare const sanitizeLines: (str: string) => string;
  * - Used when you're running a query against a string entered by a user.
  *
  * @example normalizeString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
- */
-export declare const simplifyString: (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.
  *
- * Note: this splits words based on spaces, so won't work well with logographic writing systems e.g. kanji.
+ * @todo Convert letter-like characters (e.g. `ℝ`) to their ASCII equivalent (e.g. `R`).
  */
-export declare const getSlug: (str: string) => string;
+export declare const simplifyString: (str: string) => string;
+/** Convert a string to a `kebab-case` URL slug, or throw `AssertionError` */
+export declare const getOptionalSlug: (str: string) => string | null;
+export declare function getSlug(str: string): string;
+/** Convert a string to a unique ref e.g. `abc123`, or `null` */
+export declare const getOptionalRef: (str: string) => string | null;
+/** Convert a string to a unique ref e.g. `abc123`, or throw `AssertionError` */
+export declare function getRef(str: string): string;
 /**
  * Return an array of the separate words and "quoted phrases" found in a string.
  * - Phrases enclosed "in quotes" are a single word.

package/util/string.js

@@ -53,9 +53,9 @@ export function assertStringLength(str, min = 1, max = Infinity) {
         throw new AssertionError(`Must be string with length ${formatRange(min, max)}`, str);
 }
 /** Get a string if it has the specified minimum length.  */
-export function getStringLength(arr, min = 1, max = Infinity) {
-    assertStringLength(arr, min, max);
-    return arr;
+export function getStringLength(str, min = 1, max = Infinity) {
+    assertStringLength(str, min, max);
+    return str;
 }
 /** Concatenate an iterable set of strings together. */
 export const joinStrings = (strs, joiner = "") => getArray(strs).join(joiner);
@@ -99,6 +99,8 @@ export const sanitizeLines = (str) => str
  * - Used when you're running a query against a string entered by a user.
  *
  * @example normalizeString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
+ *
+ * @todo Convert letter-like characters (e.g. `ℝ`) to their ASCII equivalent (e.g. `R`).
  */
 export const simplifyString = (str) => str
     .normalize("NFD") // Convert ligatures (e.g. `ff`) and letters with marks (e.g. `ü`) to separate characters (e.g. `ff` and `u◌̈`)`.
@@ -106,14 +108,24 @@ export const simplifyString = (str) => str
     .replace(/[^\p{L}\p{N} ]+/gu, "") // Strip characters that aren't letters, numbers, spaces.
     .trim()
     .toLowerCase();
-/**
- * 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.
- *
- * Note: this splits words based on spaces, so won't work well with logographic writing systems e.g. kanji.
- */
-export const getSlug = (str) => simplifyString(str).replace(/ /g, "-");
+/** Convert a string to a `kebab-case` URL slug, or throw `AssertionError` */
+export const getOptionalSlug = (str) => simplifyString(str).replace(/ /g, "-") || null;
+/* Convert a string to a `kebab-case` URL slug, or throw `AssertionError` */
+export function getSlug(str) {
+    const slug = getOptionalSlug(str);
+    if (slug)
+        return slug;
+    throw new AssertionError(`String slug cannot be empty (received "${str}")`);
+}
+/** Convert a string to a unique ref e.g. `abc123`, or `null` */
+export const getOptionalRef = (str) => simplifyString(str).replace(/ /g, "") || null;
+/** Convert a string to a unique ref e.g. `abc123`, or throw `AssertionError` */
+export function getRef(str) {
+    const ref = getOptionalRef(str);
+    if (ref)
+        return ref;
+    throw new AssertionError(`String ref cannot be empty (received "${str}")`);
+}
 /**
  * Return an array of the separate words and "quoted phrases" found in a string.
  * - Phrases enclosed "in quotes" are a single word.