shelving 1.88.0 → 1.89.1

package/db/ItemState.d.ts

@@ -14,7 +14,7 @@ export declare class ItemState<T extends Datas, K extends DataKey<T> = DataKey<T
     constructor(ref: Item<T, K> | AsyncItem<T, K>);
     /** Refresh this state from the source provider. */
     readonly refresh: () => void;
-    _refresh(): Promise<void>;
+    private _refresh;
     /** Refresh this state if data in the cache is older than `maxAge` (in milliseconds). */
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */

package/db/QueryState.d.ts

@@ -27,7 +27,7 @@ export declare class QueryState<T extends Datas, K extends DataKey<T> = DataKey<
     constructor(ref: Query<T, K> | AsyncQuery<T, K>);
     /** Refresh this state from the source provider. */
     readonly refresh: () => void;
-    _refresh(): Promise<void>;
+    private _refresh;
     /** Refresh this state if data in the cache is older than `maxAge` (in milliseconds). */
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */
@@ -37,7 +37,7 @@ export declare class QueryState<T extends Datas, K extends DataKey<T> = DataKey<
      * - Promise that needs to be handled.
      */
     readonly loadMore: () => void;
-    _loadMore(): Promise<void>;
+    private _loadMore;
     /** Iterate over the items. */
     [Symbol.iterator](): Iterator<ItemData<T[K]>>;
 }

package/package.json

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

package/react/createCache.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="react" />
+/**
+ * Interface for a cache controller.
+ * - Cache is a `Map` indexed by strings that can be used to store any value.
+ */
+export interface CacheController<T> {
+    /** Wrap around a set of elements to provide the cache to them. */
+    readonly Cache: ({ children }: {
+        children: React.ReactNode;
+    }) => React.ReactElement;
+    /** Use the current cache map in a component. */
+    readonly useCache: () => Map<string, T>;
+}
+/** Create a cache. */
+export declare function createCache<T>(): CacheController<T>;

package/react/createCache.js

@@ -0,0 +1,21 @@
+import { useContext, createContext, createElement } from "react";
+import { ConditionError } from "../error/ConditionError.js";
+import { useReduce } from "./useReduce.js";
+/** Reducer that gets an existing `Map` instance or creates a new one. */
+const _reduceMap = (previous) => previous || new Map();
+/** Create a cache. */
+export function createCache() {
+    const context = createContext(undefined);
+    return {
+        useCache: () => {
+            const cache = useContext(context);
+            if (!cache)
+                throw new ConditionError("useCache() must be used inside <Cache>");
+            return cache;
+        },
+        Cache: ({ children }) => {
+            const cache = useReduce(_reduceMap);
+            return createElement(context.Provider, { children, value: cache });
+        },
+    };
+}

package/react/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";
-export * from "./useCache.js";
+export * from "./createCache.js";
 export * from "./useSequence.js";
 export * from "./useState.js";
 export * from "./useData.js";

package/react/index.js

@@ -2,7 +2,7 @@
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";
-export * from "./useCache.js";
+export * from "./createCache.js";
 // Integration.
 export * from "./useSequence.js";
 export * from "./useState.js";

package/react/useData.d.ts

@@ -1,15 +1,18 @@
+/// <reference types="react" />
 import type { ImmutableArray } from "../util/array.js";
-import { DataKey, Datas } from "../util/data.js";
 import { AsyncItem } from "../db/Item.js";
 import { ItemState } from "../db/ItemState.js";
 import { AsyncQuery } from "../db/Query.js";
 import { QueryState } from "../db/QueryState.js";
-type Reference<T extends Datas, K extends DataKey<T>> = AsyncItem<T, K> | AsyncQuery<T, K>;
-type ReferenceReferenceState<T extends Reference<Datas, string>> = T extends AsyncItem<infer D, infer K> ? ItemState<D, K> : T extends AsyncQuery<infer D, infer K> ? QueryState<D, K> : never;
+type AnyRef = AsyncItem<any, any> | AsyncQuery<any, any>;
+type RefToState<T> = T extends undefined ? undefined : T extends AsyncItem<infer D, infer K> ? ItemState<D, K> : T extends AsyncQuery<infer D, infer K> ? QueryState<D, K> : never;
 /** Use one or more data items or queries. */
-export declare function useData<T extends Reference<Datas, string>>(ref: T): ReferenceReferenceState<T>;
-export declare function useData<T extends Reference<Datas, string>>(ref: T | undefined): ReferenceReferenceState<T> | undefined;
-export declare function useData<T extends ImmutableArray<Reference<Datas, string>>>(...refs: T): {
-    [K in keyof T]: ReferenceReferenceState<T[K]>;
+export declare function useData<T extends AnyRef | undefined>(ref: T): RefToState<T>;
+export declare function useData<T extends ImmutableArray<AnyRef | undefined>>(...refs: T): {
+    [K in keyof T]: RefToState<T[K]>;
 };
+/** Wrap components with `<DataCache>` to allow the use of `useData()`. */
+export declare const DataCache: ({ children }: {
+    children: import("react").ReactNode;
+}) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
 export {};

package/react/useData.js

@@ -4,14 +4,18 @@ import { AsyncItem } from "../db/Item.js";
 import { ItemState } from "../db/ItemState.js";
 import { QueryState } from "../db/QueryState.js";
 import { useState } from "./useState.js";
-import { useCache } from "./useCache.js";
+import { createCache } from "./createCache.js";
+/** Create a cache. */
+const { Cache, useCache } = createCache();
 export function useData(...refs) {
     const cache = useCache();
-    const states = mapArray(refs, _getReferenceState, cache);
+    const states = mapArray(refs, _getRefState, cache);
     return useState(...states);
 }
 /** Get the corresponding `ItemState` or `QueryState` instance from the cache for a given `Item` or `Query`. */
-function _getReferenceState(ref, cache) {
+function _getRefState(ref, cache) {
     const key = ref === null || ref === void 0 ? void 0 : ref.toString();
     return ref && key ? cache.get(key) || setMapItem(cache, key, ref instanceof AsyncItem ? new ItemState(ref) : new QueryState(ref)) : undefined;
 }
+/** Wrap components with `<DataCache>` to allow the use of `useData()`. */
+export const DataCache = Cache;

package/util/data.d.ts

@@ -36,9 +36,12 @@ export declare function assertData<T extends Data>(value: T | unknown): asserts
 export declare const isDataProp: <T extends Data>(obj: T, key: unknown) => key is DataKey<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: OptionalData<T>): T;
-/** Get the props of a data object. */
+/** Get the props of a data object as a set of entries. */
 export declare function getDataProps<T extends Data>(data: T): ImmutableArray<DataProp<T>>;
 export declare function getDataProps<T extends Data>(data: T | Partial<T>): ImmutableArray<DataProp<T>>;
+/** Get the props of a data object as a set of entries. */
+export declare function getDataKeys<T extends Data>(data: T): ImmutableArray<DataKey<T>>;
+export declare function getDataKeys<T extends Data>(data: T | Partial<T>): ImmutableArray<DataKey<T>>;
 /** Type that represents an empty data object. */
 export type EmptyData = {
     readonly [K in never]: never;

package/util/data.js

@@ -19,6 +19,9 @@ export function getData(result) {
 export function getDataProps(data) {
     return Object.entries(data);
 }
+export function getDataKeys(data) {
+    return Object.keys(data);
+}
 /** An empty object. */
 export const EMPTY_DATA = { __proto__: null };
 /** Function that returns an an empty object. */

package/util/object.d.ts

@@ -67,6 +67,10 @@ export type OmitProps<T, TT> = Omit<T, {
 export declare function getProps<T extends ImmutableObject>(obj: T): ImmutableArray<ObjectProp<T>>;
 export declare function getProps<T extends ImmutableObject>(obj: T | Partial<T>): ImmutableArray<ObjectProp<T>>;
 export declare function getProps<T extends ImmutableObject>(obj: T | Partial<T> | Iterable<ObjectProp<T>>): Iterable<ObjectProp<T>>;
+/** Get the keys of an object as an array. */
+export declare function getKeys<T extends ImmutableObject>(obj: T): ImmutableArray<ObjectKey<T>>;
+export declare function getKeys<T extends ImmutableObject>(obj: T | Partial<T>): ImmutableArray<ObjectKey<T>>;
+export declare function getKeys<T extends ImmutableObject>(obj: T | Partial<T> | Iterable<ObjectKey<T>>): Iterable<ObjectKey<T>>;
 /**
  * Extract the value of a named prop from an object.
  * - Extraction is possibly deep if deeper keys are specified.

package/util/object.js

@@ -26,6 +26,9 @@ export const isProp = (obj, key) => Object.prototype.hasOwnProperty.call(obj, ke
 export function getProps(obj) {
     return isIterable(obj) ? obj : Object.entries(obj);
 }
+export function getKeys(obj) {
+    return isIterable(obj) ? obj : Object.keys(obj);
+}
 export function getProp(obj, key, ...keys) {
     const value = obj[key];
     return !isArrayLength(keys) ? value : isObject(value) ? getProp(value, ...keys) : undefined;

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/react/useCache.d.ts

@@ -1,46 +0,0 @@
-/// <reference types="react" />
-/**
- * Controller that creates an independent cache.
- * - The cache is a `Map` instance that stores indexed items.
- */
-export declare class CacheController<T> {
-    protected _context: import("react").Context<Map<string, T> | undefined>;
-    /** Use this cache in a component. */
-    readonly useCache: () => Map<string, T>;
-    /** Component that provides a cache of this type to its children. */
-    readonly Cache: ({ children }: {
-        children: React.ReactNode;
-    }) => React.ReactElement | null;
-}
-/**
- * Default cache
- * - This is a flexible generic cache intended to be the default.
- * - Use this cache unless you want to cache a completely independent set of items without interference.
- */
-export declare const CACHE: CacheController<any>;
-/**
- * Use a global cache in a component.
- * - Throws an error if used outside of `<Cache>`
- */
-export declare const useCache: <T>() => Map<string, T>;
-/**
- * Component that provides a global cache to its children.
- *
- * Note: If mounted globally this cache will bloat over time, so you need a strategy to clear or reset the cache occasionally.
- *
- * A good strategy is to wrap a separate `<Cache>` around each page of your app.
- * This means the cache can only grow to the size of each page and the memory is released when the user navigates to a new page.
- * You might need to use `<Cache key="something unique to the page">` to ensure the cache component is destroyed and remounted for each page.
- *
- * Put a `<Suspense>` boundary _inside_ `<Cache>`
- * - This prevents promises being thrown up through the cache causing it to be destroyed.
- * - When the promise resolves and the render is tried again the data would not exist (because the cache was destroyed).
- * - This will cause an infinite loading loop.
- *
- * Put your error boundary _outside_ your `<Cache>`
- * - The error being thrown up through the cache causes it to be destroyed.
- * - This means when the uses tells the error boundary to try again (if supported) all data on the page will be retried.
- */
-export declare const Cache: ({ children }: {
-    children: React.ReactNode;
-}) => React.ReactElement | null;

package/react/useCache.js

@@ -1,56 +0,0 @@
-import { useContext, createContext, createElement } from "react";
-import { ConditionError } from "../error/ConditionError.js";
-import { useReduce } from "./useReduce.js";
-/**
- * Controller that creates an independent cache.
- * - The cache is a `Map` instance that stores indexed items.
- */
-export class CacheController {
-    constructor() {
-        this._context = createContext(undefined);
-        /** Use this cache in a component. */
-        this.useCache = () => {
-            const cache = useContext(this._context);
-            if (!cache)
-                throw new ConditionError("useCache() must be used inside <Cache>");
-            return cache;
-        };
-        /** Component that provides a cache of this type to its children. */
-        this.Cache = ({ children }) => {
-            const cache = useReduce(_reduceMap);
-            return createElement(this._context.Provider, { children, value: cache });
-        };
-    }
-}
-/** Reducer that gets an existing `Map` instance or creates a new one. */
-const _reduceMap = (previous) => previous || new Map();
-/**
- * Default cache
- * - This is a flexible generic cache intended to be the default.
- * - Use this cache unless you want to cache a completely independent set of items without interference.
- */
-export const CACHE = new CacheController(); // eslint-disable-line @typescript-eslint/no-explicit-any
-/**
- * Use a global cache in a component.
- * - Throws an error if used outside of `<Cache>`
- */
-export const useCache = CACHE.useCache;
-/**
- * Component that provides a global cache to its children.
- *
- * Note: If mounted globally this cache will bloat over time, so you need a strategy to clear or reset the cache occasionally.
- *
- * A good strategy is to wrap a separate `<Cache>` around each page of your app.
- * This means the cache can only grow to the size of each page and the memory is released when the user navigates to a new page.
- * You might need to use `<Cache key="something unique to the page">` to ensure the cache component is destroyed and remounted for each page.
- *
- * Put a `<Suspense>` boundary _inside_ `<Cache>`
- * - This prevents promises being thrown up through the cache causing it to be destroyed.
- * - When the promise resolves and the render is tried again the data would not exist (because the cache was destroyed).
- * - This will cause an infinite loading loop.
- *
- * Put your error boundary _outside_ your `<Cache>`
- * - The error being thrown up through the cache causes it to be destroyed.
- * - This means when the uses tells the error boundary to try again (if supported) all data on the page will be retried.
- */
-export const Cache = CACHE.Cache;