shelving 1.27.0 → 1.30.1

package/api/Resource.js

@@ -1,4 +1,4 @@
-import { UNDEFINED, validate } from "../util/index.js";
+import { GET_UNDEFINED, validate } from "../util/index.js";
 import { Feedback } from "../feedback/index.js";
 import { ResourceValidationError } from "./errors.js";
 /**
@@ -37,6 +37,6 @@ export class Resource {
         }
     }
 }
-export function RESOURCE(payload = UNDEFINED, result = UNDEFINED) {
+export function RESOURCE(payload = GET_UNDEFINED, result = GET_UNDEFINED) {
     return new Resource(payload, result);
 }

package/db/Database.d.ts

@@ -1,8 +1,8 @@
-import { Entry, Observable, Observer, Result, Unsubscriber, ResultsMap, Validatable, Validator, Key, Data, Results, Datas, Validators, ValidatorType, Dispatcher } from "../util/index.js";
+import { Entry, Observable, Observer, Result, Unsubscriber, ResultsMap, Validatable, Validator, Key, Data, Results, Datas, Validators, ValidatorType, Dispatcher, Nullish } from "../util/index.js";
 import { PropUpdates, Update } from "../update/index.js";
 import type { Provider } from "../provider/Provider.js";
 import { Filters, Sorts, Query } from "../query/index.js";
-import { DocumentDelete, DocumentSet, DocumentUpdate, Write, Writes } from "./Write.js";
+import { DocumentDelete, DocumentSet, DocumentUpdate, Write } from "./Write.js";
 /**
  * Combines a database model and a provider.
  *
@@ -18,10 +18,10 @@ export declare class Database<V extends Validators<Datas> = Validators<Datas>> {
     query<K extends Key<V>>(collection: K, filters?: Filters<ValidatorType<V[K]>>, sorts?: Sorts<ValidatorType<V[K]>>, limit?: number | null): DataQuery<ValidatorType<V[K]>>;
     /** Reference a document in a collection in this model. */
     doc<K extends Key<V>>(collection: K, id: string): DataDocument<ValidatorType<V[K]>>;
-    /** Perform a write on this database and return the `Write` instance representing the changes. */
-    write(write: Write): Promise<Write>;
-    /** Perform multiple writes on this database by combining them into a single `Writes` instance representing the changes. */
-    writes(...writes: (Write | undefined)[]): Promise<Writes>;
+    /** Create a writer for this database from a set of separate writes. */
+    writer(...writes: Nullish<Write>[]): Write;
+    /** Perform one or more writes on this database and return the `Writes` instance representing the combined changes. */
+    write(...writes: Nullish<Write>[]): Promise<Write>;
 }
 /** A documents reference within a specific database. */
 export declare class DataQuery<T extends Data = Data> extends Query<T> implements Observable<Results<T>>, Validatable<Results<T>>, Iterable<Entry<T>> {

package/db/Database.js

@@ -1,4 +1,4 @@
-import { callAsync, getFirstItem, throwAsync, validate, toMap, countItems, TransformObserver, } from "../util/index.js";
+import { callAsync, getFirstItem, throwAsync, validate, toMap, countItems, TransformObserver, NOT_NULLISH, } from "../util/index.js";
 import { DataUpdate, Update } from "../update/index.js";
 import { Feedback, InvalidFeedback } from "../feedback/index.js";
 import { Filters, Query, EqualFilter } from "../query/index.js";
@@ -25,14 +25,13 @@ export class Database {
     doc(collection, id) {
         return new DataDocument(this.provider, this.validators[collection], collection, id);
     }
-    /** Perform a write on this database and return the `Write` instance representing the changes. */
-    async write(write) {
-        await write.transform(this);
-        return write;
+    /** Create a writer for this database from a set of separate writes. */
+    writer(...writes) {
+        return new Writes(...writes.filter(NOT_NULLISH));
     }
-    /** Perform multiple writes on this database by combining them into a single `Writes` instance representing the changes. */
-    async writes(...writes) {
-        const write = new Writes(...writes);
+    /** Perform one or more writes on this database and return the `Writes` instance representing the combined changes. */
+    async write(...writes) {
+        const write = new Writes(...writes.filter(NOT_NULLISH));
         await write.transform(this);
         return write;
     }

package/db/Write.d.ts

@@ -12,7 +12,7 @@ export declare abstract class Write implements Transformable<Database, void | Pr
  */
 export declare class Writes extends Write {
     readonly writes: ImmutableArray<Write>;
-    constructor(...writes: (Write | undefined)[]);
+    constructor(...writes: Write[]);
     transform(db: Database): Promise<void>;
 }
 /** Represent a write made to a single document in a database. */

package/db/Write.js

@@ -1,5 +1,5 @@
 import { DataUpdate, Update } from "../update/index.js";
-import { transform, IS_DEFINED } from "../util/index.js";
+import { transform } from "../util/index.js";
 /** Represent a write made to a database. */
 export class Write {
 }
@@ -11,7 +11,7 @@ export class Write {
 export class Writes extends Write {
     constructor(...writes) {
         super();
-        this.writes = writes.filter(IS_DEFINED);
+        this.writes = writes;
     }
     async transform(db) {
         for (const writes of this.writes)

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.27.0",
+	"version": "1.30.1",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -63,20 +63,20 @@
 		"@types/jest": "^27.0.3",
 		"@types/react": "^17.0.37",
 		"@types/react-dom": "^17.0.11",
-		"@typescript-eslint/eslint-plugin": "^5.5.0",
-		"@typescript-eslint/parser": "^5.5.0",
-		"eslint": "^8.4.0",
+		"@typescript-eslint/eslint-plugin": "^5.6.0",
+		"@typescript-eslint/parser": "^5.6.0",
+		"eslint": "^8.4.1",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-import": "^2.25.3",
 		"eslint-plugin-prettier": "^4.0.0",
-		"firebase": "^9.6.0",
-		"jest": "^27.4.3",
+		"firebase": "^9.6.1",
+		"jest": "^27.4.4",
 		"jest-ts-webcompat-resolver": "^1.0.0",
 		"prettier": "^2.5.1",
 		"react": "^17.0.2",
 		"react-dom": "^17.0.2",
-		"ts-jest": "^27.0.7",
-		"typescript": "^4.5.2"
+		"ts-jest": "^27.1.1",
+		"typescript": "^4.5.3"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=4.0.0",

package/schema/StringSchema.d.ts

@@ -1,6 +1,8 @@
 import { Schema } from "./Schema.js";
 /** `type=""` prop for HTML `<input />` tags that are relevant for strings. */
 export declare type HtmlInputType = "text" | "password" | "color" | "date" | "email" | "number" | "tel" | "search" | "url";
+/** Function that sanitizes a string. */
+export declare type Sanitizer = (str: string) => string;
 /**
  * Schema that defines a valid string.
  *
@@ -27,16 +29,16 @@ export declare class StringSchema extends Schema<string> {
     readonly min: number;
     readonly max: number | null;
     readonly match: RegExp | null;
+    readonly sanitizer: Sanitizer | null;
     readonly multiline: boolean;
-    readonly trim: boolean;
-    constructor({ value, type, min, max, match, multiline, trim, ...rest }: ConstructorParameters<typeof Schema>[0] & {
+    constructor({ value, type, min, max, match, sanitizer, multiline, ...rest }: ConstructorParameters<typeof Schema>[0] & {
         readonly value?: string;
         readonly type?: HtmlInputType;
         readonly min?: number;
         readonly max?: number | null;
         readonly match?: RegExp | null;
+        readonly sanitizer?: Sanitizer | null;
         readonly multiline?: boolean;
-        readonly trim?: boolean;
     });
     validate(unsafeValue?: unknown): string;
     /**

package/schema/StringSchema.js

@@ -22,15 +22,15 @@ import { Schema } from "./Schema.js";
  *  schema.validate('j'); // Throws 'Minimum 3 chaacters'
  */
 export class StringSchema extends Schema {
-    constructor({ value = "", type = "text", min = 0, max = null, match = null, multiline = false, trim = true, ...rest }) {
+    constructor({ value = "", type = "text", min = 0, max = null, match = null, sanitizer = null, multiline = false, ...rest }) {
         super(rest);
         this.type = type;
         this.value = value;
         this.min = min;
         this.max = max;
         this.match = match;
+        this.sanitizer = sanitizer;
         this.multiline = multiline;
-        this.trim = trim;
     }
     validate(unsafeValue = this.value) {
         const unsafeString = typeof unsafeValue === "number" ? unsafeValue.toString() : unsafeValue;
@@ -51,7 +51,7 @@ export class StringSchema extends Schema {
      * - Applies `options.sanitizer` too (if it's set).
      */
     sanitize(uncleanString) {
-        return this.multiline ? sanitizeLines(uncleanString, this.trim) : sanitizeString(uncleanString, this.trim);
+        return this.sanitizer ? this.sanitizer(uncleanString) : this.multiline ? sanitizeLines(uncleanString) : sanitizeString(uncleanString);
     }
 }
 /** Valid string, e.g. `Hello there!` */

package/stream/DataState.d.ts

@@ -1,9 +1,24 @@
-import { Key, Data, PropTransformers } from "../util/index.js";
+import { Key, Data, PropTransformers, Result } from "../util/index.js";
 import { State } from "./State.js";
-/** State that stores an array and has additional methods to help with that. */
+/** State that stores a data object and has additional methods to help with that. */
 export declare class DataState<T extends Data> extends State<T> {
+    /** Get the data value of this state. */
+    get data(): T;
     /** Set a prop in this object to a new value. */
     set<K extends Key<T>>(key: K, value: T[K]): void;
     /** Update several props in this object. */
     update(updates: PropTransformers<T>): void;
 }
+/** State that stores an optional data object and has additional methods to help with that. */
+export declare class ResultState<T extends Data> extends State<Result<T>> {
+    /** Get the result value of this state. */
+    get result(): Result<T>;
+    /** Get current data value of this state (or throw `Promise` that resolves to the next required value). */
+    get data(): T;
+    /** Set a prop in this object to a new value. */
+    set<K extends Key<T>>(key: K, value: T[K]): void;
+    /** Update several props in this object. */
+    update(updates: PropTransformers<T>): void;
+    /** Delete this result. */
+    delete(): void;
+}

package/stream/DataState.js

@@ -1,13 +1,44 @@
-import { withProp, transformData } from "../util/index.js";
+import { withProp, transformData, NOERROR, LOADING, awaitNext, getData } from "../util/index.js";
 import { State } from "./State.js";
-/** State that stores an array and has additional methods to help with that. */
+/** State that stores a data object and has additional methods to help with that. */
 export class DataState extends State {
+    /** Get the data value of this state. */
+    get data() {
+        return this.value;
+    }
     /** Set a prop in this object to a new value. */
     set(key, value) {
-        this.next(withProp(this.value, key, value));
+        this.next(withProp(this.data, key, value));
     }
     /** Update several props in this object. */
     update(updates) {
-        this.next(transformData(this.value, updates));
+        this.next(transformData(this.data, updates));
+    }
+}
+/** State that stores an optional data object and has additional methods to help with that. */
+export class ResultState extends State {
+    /** Get the result value of this state. */
+    get result() {
+        return this.value;
+    }
+    /** Get current data value of this state (or throw `Promise` that resolves to the next required value). */
+    get data() {
+        if (this.reason !== NOERROR)
+            throw this.reason;
+        if (this._value === LOADING)
+            throw awaitNext(this).then(getData);
+        return getData(this._value);
+    }
+    /** Set a prop in this object to a new value. */
+    set(key, value) {
+        this.next(withProp(this.data, key, value));
+    }
+    /** Update several props in this object. */
+    update(updates) {
+        this.next(transformData(this.data, updates));
+    }
+    /** Delete this result. */
+    delete() {
+        this.next(undefined);
     }
 }

package/stream/State.d.ts

@@ -1,5 +1,5 @@
 import { Transformer, LOADING, ObserverType, NOERROR, Observer } from "../util/index.js";
-import { Stream } from "./Stream.js";
+import { AnyStream, Stream } from "./Stream.js";
 /** Any state (useful for `extends AnySubscribable` clauses). */
 export declare type AnyState = State<any>;
 /**
@@ -14,8 +14,11 @@ export declare type AnyState = State<any>;
  * */
 export interface State<T> {
     to(): State<T>;
+    to<O extends AnyStream>(target: O): O;
     derive<TT>(transformer: Transformer<T, TT>): State<TT>;
+    derive<O extends AnyStream>(transformer: Transformer<T, ObserverType<O>>, target: O): O;
     deriveAsync<TT>(transformer: Transformer<T, PromiseLike<TT>>): State<TT>;
+    deriveAsync<O extends AnyStream>(transformer: Transformer<T, Promise<ObserverType<O>>>, target: O): O;
 }
 export declare class State<T> extends Stream<T> {
     static [Symbol.species]: typeof State;
@@ -28,8 +31,6 @@ export declare class State<T> extends Stream<T> {
     /** Most recently dispatched value (or throw `Promise` that resolves to the next value). */
     get value(): T;
     protected _value: T | typeof LOADING;
-    /** Get current required value (or throw `Promise` that resolves to the next required value). */
-    get data(): Exclude<T, null | undefined>;
     /** Is there a current value, or is it still loading. */
     get loading(): boolean;
     /** Apply a transformer to this state. */

package/stream/State.js

@@ -1,5 +1,5 @@
 var _a;
-import { LOADING, NOERROR, dispatchNext, dispatchError, dispatchComplete, transform, getRequired, awaitNext, } from "../util/index.js";
+import { LOADING, NOERROR, dispatchNext, dispatchError, dispatchComplete, transform, awaitNext, } from "../util/index.js";
 import { Stream } from "./Stream.js";
 export class State extends Stream {
     constructor() {
@@ -22,14 +22,6 @@ export class State extends Stream {
             throw awaitNext(this);
         return this._value;
     }
-    /** Get current required value (or throw `Promise` that resolves to the next required value). */
-    get data() {
-        if (this.reason !== NOERROR)
-            throw this.reason;
-        if (this._value === LOADING)
-            throw awaitNext(this).then(getRequired);
-        return getRequired(this._value);
-    }
     /** Is there a current value, or is it still loading. */
     get loading() {
         return this._value === LOADING;

package/util/data.d.ts

@@ -25,9 +25,6 @@ export declare const isData: <T extends Data>(value: unknown) => value is T;
 /** Turn a data object into an array of entries (if it isn't one already). */
 export declare function toProps<T extends Data>(input: T): ImmutableArray<Prop<T>>;
 export declare function toProps<T extends Data>(input: Partial<T>): ImmutableArray<Prop<T>>;
-/** Get a required value (returns value or throws `RequiredError` if value is `null` or `undefined`). */
-export declare function getRequired<T>(v: T): Exclude<T, null | undefined>;
-export declare function getRequired<T>(v: T | null | undefined): T;
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export declare function getData<T extends Data>(result: Result<T>): T;
 /**
@@ -137,3 +134,11 @@ export declare type DeepMutable<T extends Data> = {
 export declare type DeepReadonly<T extends Data> = {
     +readonly [K in keyof T]: T[K] extends Data ? DeepReadonly<T[K]> : T[K];
 };
+/** Pick only the properties of an object that match a type. */
+export declare type PickProps<T, TT> = Pick<T, {
+    [K in keyof T]: T[K] extends TT ? K : never;
+}[keyof T]>;
+/** Omit the properties of an object that match a type. */
+export declare type OmitProps<T, TT> = Omit<T, {
+    [K in keyof T]: T[K] extends TT ? K : never;
+}[keyof T]>;

package/util/data.js

@@ -4,11 +4,6 @@ export const isData = (value) => typeof value === "object" && value !== null;
 export function toProps(input) {
     return Object.entries(input);
 }
-export function getRequired(v) {
-    if (v === undefined || v === null)
-        throw new RequiredError(v === null ? "Required value is null" : "Required value is undefined");
-    return v;
-}
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export function getData(result) {
     if (!result)

package/util/null.d.ts

@@ -3,4 +3,15 @@ export declare const IS_NULL: (v: unknown) => v is null;
 /** Is a value not null? */
 export declare const NOT_NULL: <T>(v: T | null) => v is T;
 /** Function that always returns null. */
-export declare const NULL: () => null;
+export declare const GET_NULL: () => null;
+/** Nullish is `null` or `undefined` */
+export declare type Nullish<T> = T | null | undefined;
+/** Nullish is `null` or `undefined` */
+export declare type NotNullish<T> = Exclude<T, null | undefined>;
+/** Is a value nullish? */
+export declare const IS_NULLISH: <T>(v: Nullish<T>) => v is null | undefined;
+/** Is a value nullish? */
+export declare const NOT_NULLISH: <T>(v: Nullish<T>) => v is T;
+/** Get a required value (returns value or throws `RequiredError` if value is `null` or `undefined`). */
+export declare function getRequired<T>(v: T): NotNullish<T>;
+export declare function getRequired<T>(v: Nullish<T>): T;

package/util/null.js

@@ -1,6 +1,16 @@
+import { RequiredError } from "../error/index.js";
 /** Is a value null? */
 export const IS_NULL = (v) => v === null;
 /** Is a value not null? */
 export const NOT_NULL = (v) => v !== null;
 /** Function that always returns null. */
-export const NULL = () => null;
+export const GET_NULL = () => null;
+/** Is a value nullish? */
+export const IS_NULLISH = (v) => v === null || v === undefined;
+/** Is a value nullish? */
+export const NOT_NULLISH = (v) => v !== null && v !== undefined;
+export function getRequired(v) {
+    if (v === undefined || v === null)
+        throw new RequiredError("Required value is missing");
+    return v;
+}

package/util/object.d.ts

@@ -87,3 +87,11 @@ export declare function deleteEntry<T>(obj: MutableObject<T>, key: string, value
  * @param entries Set of keys or entries to remove.
  */
 export declare function deleteEntries<T>(obj: MutableObject<T>, keys: ImmutableArray<string>): void;
+/** Type that represents an empty object. */
+export declare type EmptyObject = {
+    readonly [K in never]: never;
+};
+/** An empty object. */
+export declare const EMPTY_OBJECT: EmptyObject;
+/** Function that returns an an empty object. */
+export declare const GET_EMPTY_OBJECT: () => EmptyObject;

package/util/object.js

@@ -98,3 +98,7 @@ export function deleteEntries(obj, keys) {
     for (const key of keys)
         delete obj[key];
 }
+/** An empty object. */
+export const EMPTY_OBJECT = {};
+/** Function that returns an an empty object. */
+export const GET_EMPTY_OBJECT = () => EMPTY_OBJECT;

package/util/search.d.ts

@@ -36,7 +36,7 @@ export declare function MATCHES_ANY(item: unknown, regexps: ImmutableArray<RegEx
  * - Quoted phrases match fully (starting and ending with a word boundary).
  */
 export declare const toWordRegExps: (query: string) => ImmutableArray<RegExp>;
-/** Convert a string word to the corresponding set of case-insensitive regular expressions. */
+/** Convert a string to a regular expression matching the start of a word boundary. */
 export declare const toWordRegExp: (word: string) => RegExp;
 /** Matcher that matches any words in a string. */
 export declare class MatchAnyWord implements Matchable<unknown, void> {
@@ -51,7 +51,7 @@ export declare class MatchAllWords implements Matchable<unknown, void> {
     match(value: string): boolean;
 }
 /** Matcher that matches an exact phrase. */
-export declare class MatchPhrase implements Matchable<unknown, void> {
+export declare class MatchWord implements Matchable<unknown, void> {
     private _regexp;
     constructor(phrase: string);
     match(value: string): boolean;

package/util/search.js

@@ -50,9 +50,9 @@ export function MATCHES_ANY(item, regexps) {
  * - Unquoted words match partially (starting with a word boundary).
  * - Quoted phrases match fully (starting and ending with a word boundary).
  */
-export const toWordRegExps = (query) => toWords(query).map(normalizeString).map(toWordRegExp);
-/** Convert a string word to the corresponding set of case-insensitive regular expressions. */
-export const toWordRegExp = (word) => word.includes(" ") ? new RegExp(`\\b${escapeRegExp(word)}\\b`, "i") : new RegExp(`\\b${escapeRegExp(word)}`, "i");
+export const toWordRegExps = (query) => toWords(query).map(toWordRegExp);
+/** Convert a string to a regular expression matching the start of a word boundary. */
+export const toWordRegExp = (word) => new RegExp(`\\b${escapeRegExp(normalizeString(word))}`, "i");
 /** Matcher that matches any words in a string. */
 export class MatchAnyWord {
     constructor(words) {
@@ -72,7 +72,7 @@ export class MatchAllWords {
     }
 }
 /** Matcher that matches an exact phrase. */
-export class MatchPhrase {
+export class MatchWord {
     constructor(phrase) {
         this._regexp = toWordRegExp(phrase);
     }

package/util/string.d.ts

@@ -33,25 +33,25 @@ export declare function toTitle(value: unknown): string;
  * @param multiline If `true`, `\t` horizontal tabs and `\r` newlines are allowed (defaults to `false` which strips these characters).
  * @returns The clean output string.
  */
-export declare function sanitizeString(dirty: string, trim?: boolean): string;
+export declare const sanitizeString: (dirty: string) => string;
 /**
  * Sanitize a multiline string.
  * - Like `sanitizeString()` but allows `\t` horizontal tab and `\r` newline.
  */
-export declare function sanitizeLines(dirty: string, trim?: boolean): string;
+export declare const sanitizeLines: (dirty: string) => string;
 /**
  * Normalize a string so it can be compared to another string (free from upper/lower cases, symbols, punctuation).
  *
  * Does the following:
- * - Santize the string to remove control characters.
+ * - Removes control characters.
  * - Remove symbols (e.g. `$` dollar) and punctuation (e.g. `"` double quote).
  * - Remove marks (e.g. the umlout dots above `ö`).
  * - Convert spaces/separators to " " single space (e.g. line breaks, non-breaking space).
  * - Convert to lowercase and trim excess whitespace.
  *
- * @example normalizeString("Däve-is REALLY éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
+ * @example normalizeString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
  */
-export declare const normalizeString: (value: string) => string;
+export declare const normalizeString: (str: string) => string;
 /**
  * Convert a string to a `kebab-case` URL slug.
  * - Remove any characters not in the range `[a-z0-9-]`
@@ -67,6 +67,8 @@ export declare const toSlug: (value: string) => string;
  * @returns Array of the found words, e.g. `["yellow", "dog", "Golden Retriever"
  */
 export declare const toWords: (value: string) => ImmutableArray<string>;
+/** Find and iterate over the words in a string. */
+export declare function yieldWords(value: string): Generator<string, void, void>;
 /**
  * Convert a string to a regular expression that matches that string.
  *

package/util/string.js

@@ -3,7 +3,6 @@ import { formatDate } from "./date.js";
 import { isData } from "./data.js";
 import { isArray } from "./array.js";
 import { formatNumber, isBetween } from "./number.js";
-import { IS_DEFINED } from "./undefined.js";
 /** Is a value a string? */
 export const IS_STRING = (v) => typeof v === "string";
 /**
@@ -70,47 +69,40 @@ export function toTitle(value) {
  * @param multiline If `true`, `\t` horizontal tabs and `\r` newlines are allowed (defaults to `false` which strips these characters).
  * @returns The clean output string.
  */
-export function sanitizeString(dirty, trim = true) {
-    const clean = dirty.replace(CONTROLS, "").replace(SPACES, " ");
-    return trim ? clean.trim() : clean;
-}
-const CONTROLS = /[\x00-\x1F\x7F-\x9F]/g; // All control characters (`\x00`-`\x1F`, `\x7F`-`\x9F`)
-const SPACES = /\s/g; // Sanitize zero-width spacers etc.
+export const sanitizeString = (dirty) => dirty.replace(SANE_DISALLOWED, "").replace(SANE_SPACES, " ").trim();
+const SANE_DISALLOWED = /[\x00-\x1F\x7F-\x9F]/g; // All control characters (`\x00`-`\x1F`, `\x7F`-`\x9F`)
+const SANE_SPACES = /\s/g; // Zero-width spacers etc.
 /**
  * Sanitize a multiline string.
  * - Like `sanitizeString()` but allows `\t` horizontal tab and `\r` newline.
  */
-export function sanitizeLines(dirty, trim = true) {
-    const clean = dirty.replace(CONTROLS_MULTILINE, "").replace(SPACES_MULTILINE, " ");
-    return trim ? clean.replace(TRIM_END_MULTILINE, "") : clean;
-}
-const CONTROLS_MULTILINE = /(?![\t\n])[\x00-\x1F\x7F-\x9F]/g; // Control characters except `\t` horizontal tab and `\n` new line.
-const SPACES_MULTILINE = /(?![\t\n])\s/g; // All spaces except `\t` horizontal tab and `\n` new line.
-const TRIM_END_MULTILINE = /\s+$/gm;
+export const sanitizeLines = (dirty) => dirty.replace(LINES_DISALLOW, "").replace(LINES_SPACES, " ").replace(LINES_TRIM, "");
+const LINES_DISALLOW = /(?![\t\n])[\x00-\x1F\x7F-\x9F]/g; // Control characters except `\t` horizontal tab and `\n` new line.
+const LINES_TRIM = /\s+$/gm; // Spaces at the end of lines.
+const LINES_SPACES = /(?![\t\n])\s/g; // All spaces except `\t` horizontal tab and `\n` new line.
 /**
  * Normalize a string so it can be compared to another string (free from upper/lower cases, symbols, punctuation).
  *
  * Does the following:
- * - Santize the string to remove control characters.
+ * - Removes control characters.
  * - Remove symbols (e.g. `$` dollar) and punctuation (e.g. `"` double quote).
  * - Remove marks (e.g. the umlout dots above `ö`).
  * - Convert spaces/separators to " " single space (e.g. line breaks, non-breaking space).
  * - Convert to lowercase and trim excess whitespace.
  *
- * @example normalizeString("Däve-is REALLY éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
+ * @example normalizeString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
  */
-export const normalizeString = (value) => sanitizeString(value).normalize("NFD").replace(STRIP, "").replace(SEPARATORS, " ").trim().toLowerCase();
-const STRIP = /[\p{Symbol}\p{Mark}\p{Punctuation}]+/gu;
-const SEPARATORS = /\s+/g;
+export const normalizeString = (str) => str.normalize("NFD").replace(NORMAL_DISALLOW, "").replace(NORMAL_SPACES, " ").trim().toLowerCase();
+const NORMAL_DISALLOW = /[^\p{L}\p{N}\s]+/gu; // Keep letters, numbers, separators. Don't need to use `\p{Z}` because `\s` matches those already e.g. hair space and nbsp.
+const NORMAL_SPACES = /\s+/gu; // Convert all possible separators to space.
 /**
  * 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.
  */
-export const toSlug = (value) => value.toLowerCase().normalize("NFD").replace(TO_HYPHEN, "-").replace(NON_ALPHANUMERIC, "").replace(TRIM_HYPHENS, "");
-const TO_HYPHEN = /[\s-–—_]+/g; // Anything that is a space becomes a hyphen.
-const NON_ALPHANUMERIC = /[^a-z0-9-]+/gu; // Anything that isn't [a-z0-9-] gets removed.
-const TRIM_HYPHENS = /^-+|-+$/g; // Trim excess hyphens at start and end.
+export const toSlug = (value) => value.toLowerCase().normalize("NFD").replace(SLUG_HYPHENS, "-").replace(SLUG_DISALLOWED, "");
+const SLUG_DISALLOWED = /[^a-z0-9-]+|^-+|-+$/gu; // Remove anything outside a-z and hyphen (except at start/end).
+const SLUG_HYPHENS = /[\s\-–—_]+/gu; // Anything that is a space becomes a hyphen.
 /**
  * Split a string into its separate words.
  * - Words enclosed "in quotes" are a single word.
@@ -119,8 +111,15 @@ const TRIM_HYPHENS = /^-+|-+$/g; // Trim excess hyphens at start and end.
  * @param value The input string, e.g. `yellow dog   "Golden Retriever"`
  * @returns Array of the found words, e.g. `["yellow", "dog", "Golden Retriever"
  */
-export const toWords = (value) => Array.from(value.matchAll(MATCH_WORD)).map(toWord).filter(IS_DEFINED);
-const toWord = (matches) => matches[1] || matches[0] || undefined;
+export const toWords = (value) => Array.from(yieldWords(value));
+/** Find and iterate over the words in a string. */
+export function* yieldWords(value) {
+    for (const matches of value.matchAll(MATCH_WORD)) {
+        const str = matches[1] || matches[0];
+        if (str)
+            yield str;
+    }
+}
 const MATCH_WORD = /[^\s"]+|"([^"]*)"/g;
 /**
  * Convert a string to a regular expression that matches that string.

package/util/undefined.d.ts

@@ -4,6 +4,4 @@ export declare const IS_UNDEFINED: (v: unknown) => v is undefined;
 export declare const IS_DEFINED: <T>(v: T | undefined) => v is T;
 export declare const NOT_UNDEFINED: <T>(v: T | undefined) => v is T;
 /** Function that always returns undefined. */
-export declare const UNDEFINED: () => undefined;
-/** Function that always returns void. */
-export declare const VOID: () => void;
+export declare const GET_UNDEFINED: () => undefined;

package/util/undefined.js

@@ -4,6 +4,4 @@ export const IS_UNDEFINED = (v) => v === undefined;
 export const IS_DEFINED = (v) => v !== undefined;
 export const NOT_UNDEFINED = IS_DEFINED;
 /** Function that always returns undefined. */
-export const UNDEFINED = () => undefined;
-/** Function that always returns void. */
-export const VOID = UNDEFINED;
+export const GET_UNDEFINED = () => undefined;

package/util/url.d.ts

@@ -1,10 +1,9 @@
+/** Things that can be converted to a URL instance. */
+export declare type PossibleURL = string | URL;
+export declare type PossibleOptionalURL = PossibleURL | null;
+/** Convert a possible URL to a URL or return `null` if conversion fails. */
+export declare function toURL(url: PossibleURL, base?: PossibleOptionalURL): URL | null;
+/** Convert a possible URL to a URL but throw `AssertionError` if conversion fails. */
+export declare function getURL(input: PossibleURL, base?: PossibleOptionalURL): URL;
 /** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export declare const formatUrl: (url: string | URL) => string;
-/**
- * Convert a string to a URL instance or return `null` if we can't.
- * - Automatically prepend `https://` if there's no `:` anywhere.
- *
- * @param url Base
- * @param
- */
-export declare function toURL(url: string | URL, base?: URL | string | undefined): URL | null;
+export declare const formatUrl: (url: PossibleURL) => string;

package/util/url.js

@@ -1,25 +1,26 @@
-import { getRequired } from "./data.js";
-/** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export const formatUrl = (url) => {
-    const { host, pathname } = getRequired(toURL(url));
-    return `${host}${pathname.length > 1 ? pathname : ""}`;
-};
-/**
- * Convert a string to a URL instance or return `null` if we can't.
- * - Automatically prepend `https://` if there's no `:` anywhere.
- *
- * @param url Base
- * @param
- */
-export function toURL(url, base = typeof window === "object" ? window.location.href : undefined) {
+import { AssertionError } from "../error/index.js";
+/** Convert a possible URL to a URL or return `null` if conversion fails. */
+export function toURL(url, base = typeof window === "object" ? window.location.href : null) {
     if (url instanceof URL)
         return url;
     if (!url)
         return null;
     try {
-        return new URL(url, base);
+        return new URL(url, base || undefined);
     }
     catch (e) {
         return null;
     }
 }
+/** Convert a possible URL to a URL but throw `AssertionError` if conversion fails. */
+export function getURL(input, base) {
+    const url = toURL(input, base);
+    if (!url)
+        throw new AssertionError("Invalid URL", input);
+    return url;
+}
+/** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
+export const formatUrl = (url) => {
+    const { host, pathname } = getURL(url);
+    return `${host}${pathname.length > 1 ? pathname : ""}`;
+};