shelving 1.89.0 → 1.89.2

package/package.json

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

package/util/object.d.ts

@@ -1,5 +1,5 @@
 import { ImmutableArray } from "./array.js";
-/** Any readonly objet. */
+/** Any readonly object. */
 export type ImmutableObject<K extends PropertyKey = PropertyKey, T = unknown> = {
     readonly [KK in K]: T;
 };
@@ -13,6 +13,8 @@ export type ObjectProp<T extends ImmutableObject = ImmutableObject> = readonly [
 export type ObjectKey<T extends ImmutableObject = ImmutableObject> = keyof T;
 /** Value for an object prop. */
 export type ObjectValue<T extends ImmutableObject = ImmutableObject> = T[keyof T];
+/** Something that can be converted to an object. */
+export type PossibleObject<T extends ImmutableObject> = T | Iterable<ObjectProp<T>>;
 /** Is an unknown value an unknown object? */
 export declare const isObject: <T extends ImmutableObject<PropertyKey, unknown>>(value: unknown) => value is T;
 /** Assert that a value is an object */
@@ -23,6 +25,8 @@ export declare function isPlainObject(value: ImmutableObject | unknown): value i
 export declare function assertPlainObject(value: ImmutableObject | unknown): asserts value is ImmutableObject;
 /** Is an unknown value the key for an own prop of an object. */
 export declare const isProp: <T extends ImmutableObject<PropertyKey, unknown>>(obj: T, key: unknown) => key is keyof T;
+/** turn a possible object into an object. */
+export declare function getObject<T extends ImmutableObject>(obj: PossibleObject<T>): T;
 /**
  * Mutable type is the opposite of `Readonly<T>` helper type.
  * - See https://github.com/microsoft/TypeScript/issues/24509

package/util/object.js

@@ -23,6 +23,10 @@ export function assertPlainObject(value) {
 }
 /** Is an unknown value the key for an own prop of an object. */
 export const isProp = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+/** turn a possible object into an object. */
+export function getObject(obj) {
+    return isIterable(obj) ? Object.fromEntries(obj) : obj;
+}
 export function getProps(obj) {
     return isIterable(obj) ? obj : Object.entries(obj);
 }

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.

package/util/transform.d.ts

@@ -2,7 +2,7 @@ import type { ArrayItem, ImmutableArray } from "./array.js";
 import type { Entry } from "./entry.js";
 import { Arguments } from "./function.js";
 import { ImmutableObject, ObjectValue } from "./object.js";
-import { ImmutableDictionary } from "./dictionary.js";
+import { ImmutableDictionary, PossibleDictionary } from "./dictionary.js";
 /** Object that transforms an input value into an output value with its `transform()` method. */
 export interface Transformable<I, O, A extends Arguments = []> {
     transform(input: I, ...args: A): O;
@@ -38,7 +38,7 @@ export declare function mapObject<T extends ImmutableObject>(obj: T, transformer
 export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transformer: (v: ObjectValue<I>, ...args: A) => ObjectValue<O>, ...args: A): O;
 export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transformer: Transformer<ObjectValue<I>, ObjectValue<O>>, ...args: A): O;
 /** Modify the values of a dictionary using a transformer. */
-export declare const mapDictionary: <I, O, A extends Arguments = []>(dictionary: ImmutableDictionary<I>, transformer: Transformer<I, O, A>, ...args: A) => ImmutableDictionary<O>;
+export declare const mapDictionary: <I, O, A extends Arguments = []>(dictionary: PossibleDictionary<I>, transformer: Transformer<I, O, A>, ...args: A) => ImmutableDictionary<O>;
 /** Modify the values of a set of entries using a transformer. */
 export declare function mapEntries<K, I, O, A extends Arguments = []>(entries: Iterable<Entry<K, I>>, transformer: Transformer<I, O, A>, ...args: A): Iterable<Entry<K, O>>;
 /** Set of named transformers for a data object (or `undefined` to skip the transform). */

package/util/validate.d.ts

@@ -1,5 +1,5 @@
 import type { Entry } from "./entry.js";
-import type { ImmutableDictionary } from "./dictionary.js";
+import { ImmutableDictionary, PossibleDictionary } from "./dictionary.js";
 import { Data, DataProp } from "./data.js";
 import { ImmutableArray } from "./array.js";
 /** Object that can validate an unknown value with its `validate()` method. */
@@ -62,7 +62,7 @@ export declare function validateEntries<T>(unsafeValues: Iterable<Entry<string,
  * @throw InvalidFeedback if one or more entry values did not validate.
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
-export declare function validateDictionary<T>(obj: ImmutableDictionary<T>, validator: Validator<T>): ImmutableDictionary<T>;
+export declare function validateDictionary<T>(obj: PossibleDictionary<T>, validator: Validator<T>): ImmutableDictionary<T>;
 /**
  * Validate the props of a data object with a set of validators.
  *

package/util/validate.js

@@ -1,5 +1,6 @@
 import { isFeedback } from "../feedback/Feedback.js";
 import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
+import { getDictionaryItems } from "./dictionary.js";
 import { getDataProps } from "./data.js";
 import { getArray } from "./array.js";
 /** Validate an unknown value with a validator. */
@@ -69,7 +70,7 @@ export function* validateEntries(unsafeValues, validator) {
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
 export function validateDictionary(obj, validator) {
-    return Object.fromEntries(validateEntries(Object.entries(obj), validator));
+    return Object.fromEntries(validateEntries(getDictionaryItems(obj), validator));
 }
 /**
  * Validate the props of a data object with a set of validators.