shelving 1.181.2 → 1.182.0

package/util/query.d.ts

@@ -1,8 +1,7 @@
 import type { ImmutableArray } from "./array.js";
 import type { Data, DataPath, LeafData, LeafDataKey } from "./data.js";
-import type { Identifier, Item } from "./item.js";
 /** Query that can be applied to a list of data objects. */
-export type Query<T extends Data> = {
+export type Query<T extends Data = Data> = {
     readonly [K in LeafDataKey<T> as `${K}` | `!${K}`]?: LeafData<T>[K] | ImmutableArray<LeafData<T>[K]> | undefined;
 } & {
     readonly [K in LeafDataKey<T> as `${K}<` | `${K}<=` | `${K}>` | `${K}>=`]?: LeafData<T>[K] | undefined;
@@ -12,8 +11,6 @@ export type Query<T extends Data> = {
     readonly $order?: `${LeafDataKey<T>}` | `!${LeafDataKey<T>}` | undefined | ImmutableArray<`${LeafDataKey<T>}` | `!${LeafDataKey<T>}` | undefined>;
     readonly $limit?: number | undefined;
 };
-/** A set of query constraints for item data. */
-export type ItemQuery<I extends Identifier, T extends Data> = Query<Item<I, T>>;
 /** A single filter that can be applied to a list of data objects. */
 export type QueryFilter = {
     key: DataPath;

package/util/uri.d.ts

@@ -82,13 +82,18 @@ export declare function withURIParam(url: URL | URLString, key: string, value: u
 export declare function withURIParam(url: PossibleURI, key: string, value: unknown, caller?: AnyCaller): URI;
 /**
  * Return a URI with several new params set (or same URI if no changes were made).
- * - Param with `undefined` value will be ignored.
+ * - Any params with `undefined` value will be ignored.
+ *
+ * @param params A set of possible URI params.
+ * - If `params` is `null` or `undefined` the same input URL will be returned.
  *
  * @throws `ValueError` if any of the values could not be converted to strings.
  */
-export declare function withURIParams(url: URL | URLString, params: PossibleURIParams, caller?: AnyCaller): URL;
-export declare function withURIParams(url: PossibleURI, params: PossibleURIParams, caller?: AnyCaller): URI;
-/** Return a URI without one or more params (or same URI if no changes were made). */
+export declare function withURIParams(url: URL | URLString, params: Nullish<PossibleURIParams>, caller?: AnyCaller): URL;
+export declare function withURIParams(url: PossibleURI, params: Nullish<PossibleURIParams>, caller?: AnyCaller): URI;
+/**
+ * Return a URI without one or more params (or same URI if no changes were made).
+ */
 export declare function omitURIParams(url: URL | URLString, ...keys: string[]): URL;
 export declare function omitURIParams(url: PossibleURI, ...keys: string[]): URI;
 /** Return a URI without a param (or same URI if no changes were made). */

package/util/uri.js

@@ -110,6 +110,8 @@ export function withURIParam(url, key, value, caller = withURIParam) {
 }
 export function withURIParams(url, params, caller = withURIParams) {
     const input = requireURI(url, caller);
+    if (!params)
+        return input;
     const output = new URI(input);
     for (const [key, str] of getURIEntries(params, caller))
         output.searchParams.set(key, str);
@@ -117,6 +119,8 @@ export function withURIParams(url, params, caller = withURIParams) {
 }
 export function omitURIParams(url, ...keys) {
     const input = requireURI(url, omitURIParams);
+    if (!keys.length)
+        return input;
     const output = new URI(input);
     for (const key of keys)
         output.searchParams.delete(key);

package/api/provider/ClientAPIProvider.d.ts

@@ -1,37 +0,0 @@
-import type { AnyCaller } from "../../util/function.js";
-import { type RequestOptions } from "../../util/http.js";
-import { type PossibleURL, type URLString } from "../../util/url.js";
-import type { Endpoint } from "../endpoint/Endpoint.js";
-import type { APIProvider } from "./APIProvider.js";
-/** Options for an `APIProvider`. */
-export interface ClientAPIProviderOptions {
-    /** The common base URL for all rendered endpoint requests. */
-    readonly url: PossibleURL;
-    /** Options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
-    readonly options?: RequestOptions;
-}
-/** Provider for API endpoints rooted at a common base URL. */
-export declare class ClientAPIProvider implements APIProvider {
-    /** The common base URL for all rendered endpoint requests. */
-    readonly url: URLString;
-    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
-    readonly options: RequestOptions;
-    constructor({ url, options }: ClientAPIProviderOptions);
-    /**
-     * Create a `Request` that targets this endpoint with a given base URL.
-     * - Path `{placeholders}` are rendered from the payload.
-     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
-     * - For all other requests, payload is sent as the body.
-     *
-     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
-     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
-     */
-    getRequest<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Request;
-    /**
-     * Parse an HTTP `Response` for this endpoint.
-     * - Non-2xx responses become `ResponseError`.
-     * - Does not validate the result against the endpoint schema — use `ValidationAPIProvider` for that.
-     */
-    parseResponse<P, R>(_endpoint: Endpoint<P, R>, response: Response, caller?: AnyCaller): Promise<R>;
-    fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
-}

package/api/provider/ClientAPIProvider.js

@@ -1,51 +0,0 @@
-import { ResponseError } from "../../error/ResponseError.js";
-import { getMessage } from "../../util/error.js";
-import { getRequest, getResponseContent, mergeRequestOptions } from "../../util/http.js";
-import { omitProps } from "../../util/object.js";
-import { requireBaseURL, requireURL } from "../../util/url.js";
-/** Provider for API endpoints rooted at a common base URL. */
-export class ClientAPIProvider {
-    /** The common base URL for all rendered endpoint requests. */
-    url;
-    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
-    options;
-    constructor({ url, options = {} }) {
-        this.url = requireBaseURL(url, undefined, ClientAPIProvider);
-        this.options = options;
-    }
-    /**
-     * Create a `Request` that targets this endpoint with a given base URL.
-     * - Path `{placeholders}` are rendered from the payload.
-     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
-     * - For all other requests, payload is sent as the body.
-     *
-     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
-     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
-     */
-    getRequest(endpoint, payload, options, caller = this.getRequest) {
-        // Render the path into the base URL.
-        const url = requireURL(`.${endpoint.renderPath(payload, caller)}`, requireBaseURL(this.url, undefined, caller), caller).href;
-        // Placeholders are rendered into the path so get omitted from the body payload.
-        if (endpoint.placeholders.length)
-            return getRequest(endpoint.method, url, omitProps(payload, ...endpoint.placeholders), options);
-        // No placeholders.
-        return getRequest(endpoint.method, url, payload, options);
-    }
-    /**
-     * Parse an HTTP `Response` for this endpoint.
-     * - Non-2xx responses become `ResponseError`.
-     * - Does not validate the result against the endpoint schema — use `ValidationAPIProvider` for that.
-     */
-    async parseResponse(_endpoint, response, caller = this.parseResponse) {
-        const { ok, status } = response;
-        const content = await getResponseContent(response, caller);
-        if (!ok)
-            throw new ResponseError(getMessage(content) ?? `Error ${status}`, { code: status, cause: response, caller });
-        return content;
-    }
-    async fetch(endpoint, payload, options, caller = this.fetch) {
-        const request = this.getRequest(endpoint, payload, mergeRequestOptions(this.options, options), caller);
-        const response = await fetch(request);
-        return this.parseResponse(endpoint, response, caller);
-    }
-}

package/react/createCacheContext.d.ts

@@ -1,13 +0,0 @@
-import { type ReactElement, type ReactNode } from "react";
-/**
- * Create a cache context that can be provided to React elements and allows them to call `useCache()`
- * - Cache is a `Map` indexed by strings that can be used to store any value.
- */
-export declare function createCacheContext<T>(): {
-    /** Wrap around a set of elements to provide the cache to them. */
-    readonly CacheContext: ({ children }: {
-        children: ReactNode;
-    }) => ReactElement;
-    /** Use the current cache map in a component. */
-    readonly useCache: () => Map<string, T>;
-};

package/react/createCacheContext.js

@@ -1,22 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext } from "react";
-import { UnexpectedError } from "../error/UnexpectedError.js";
-import { useMap } from "./useMap.js";
-/**
- * Create a cache context that can be provided to React elements and allows them to call `useCache()`
- * - Cache is a `Map` indexed by strings that can be used to store any value.
- */
-export function createCacheContext() {
-    const Context = createContext(undefined);
-    const useCache = () => {
-        const cache = useContext(Context);
-        if (!cache)
-            throw new UnexpectedError("useCache() must be used inside <CacheContext>", { caller: useCache });
-        return cache;
-    };
-    const CacheContext = ({ children }) => {
-        const cache = useMap();
-        return _jsx(Context, { value: cache, children: children });
-    };
-    return { useCache, CacheContext };
-}

package/react/createDataContext.d.ts

@@ -1,26 +0,0 @@
-import type { ReactElement, ReactNode } from "react";
-import type { Collection } from "../db/collection/Collection.js";
-import type { DBProvider } from "../db/provider/DBProvider.js";
-import { ItemStore } from "../db/store/ItemStore.js";
-import { QueryStore } from "../db/store/QueryStore.js";
-import type { Data } from "../util/data.js";
-import type { Identifier } from "../util/item.js";
-import type { Nullish } from "../util/null.js";
-import type { ItemQuery } from "../util/query.js";
-export interface DataContext<I extends Identifier = Identifier> {
-    /** Get an `ItemStore` for the specified collection item in the current `DataProvider` context and subscribe to any changes in it. */
-    useItem<T extends Data>(this: void, collection: Collection<string, I, T>, id: I): ItemStore<I, T>;
-    useItem<T extends Data>(this: void, collection: Nullish<Collection<string, I, T>>, id: Nullish<I>): ItemStore<I, T> | undefined;
-    /** Get an `QueryStore` for the specified collection query in the current `DataProvider` context and subscribe to any changes in it. */
-    useQuery<T extends Data>(this: void, collection: Collection<string, I, T>, query: ItemQuery<I, T>): QueryStore<I, T>;
-    useQuery<T extends Data>(this: void, collection: Nullish<Collection<string, I, T>>, query: Nullish<ItemQuery<I, T>>): QueryStore<I, T> | undefined;
-    readonly DataContext: ({ children }: {
-        children: ReactNode;
-    }) => ReactElement;
-}
-/**
- * Create a data context
- * - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
- * - If the database has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
- */
-export declare function createDataContext<I extends Identifier = Identifier>(provider: DBProvider<I>): DataContext<I>;

package/react/createDataContext.js

@@ -1,31 +0,0 @@
-import { CacheDBProvider } from "../db/provider/CacheDBProvider.js";
-import { ItemStore } from "../db/store/ItemStore.js";
-import { QueryStore } from "../db/store/QueryStore.js";
-import { setMapItem } from "../util/map.js";
-import { getSource } from "../util/source.js";
-import { createCacheContext } from "./createCacheContext.js";
-import { useStore } from "./useStore.js";
-/**
- * Create a data context
- * - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
- * - If the database has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
- */
-export function createDataContext(provider) {
-    // biome-ignore lint/suspicious/noExplicitAny: The outer function enforces the type.
-    const { CacheContext, useCache } = createCacheContext();
-    // If this provider is backed by an in-memory cache, pass it to the `ItemStore` and `QueryStore` instances we create.
-    const memory = getSource(CacheDBProvider, provider)?.memory;
-    return {
-        useItem: (collection, id) => {
-            const cache = useCache();
-            const key = collection && id && `${collection.name}/${id}`;
-            return useStore(key ? cache.get(key) || setMapItem(cache, key, new ItemStore(collection, id, provider, memory)) : undefined);
-        },
-        useQuery: (collection, query) => {
-            const cache = useCache();
-            const key = collection && query && `${collection.name}?${JSON.stringify(query)}`;
-            return useStore(key ? cache.get(key) || setMapItem(cache, key, new QueryStore(collection, query, provider, memory)) : undefined);
-        },
-        DataContext: CacheContext,
-    };
-}