shelving 1.236.0 → 1.236.2

package/db/cache/CollectionCache.d.ts

@@ -10,27 +10,103 @@ import { QueryStore } from "../store/QueryStore.js";
  * Cache of `ItemStore` and `QueryStore` objects for a single collection.
  * - Use `getItem(id)` to retrieve or create the `ItemStore` for a given id.
  * - Use `getQuery(query)` to retrieve or create the `QueryStore` for a given query.
+ *
+ * @example
+ *  const cache = new CollectionCache(collection, provider);
+ *  const store = cache.getItem("abc");
+ * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache
  */
 export declare class CollectionCache<I extends Identifier, T extends Data> implements AsyncDisposable {
     private readonly _items;
     private readonly _queries;
+    /**
+     * The collection these cached stores belong to.
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/collection
+     */
     readonly collection: Collection<string, I, T>;
+    /**
+     * The database provider the cached stores fetch from.
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/provider
+     */
     readonly provider: DBProvider<I>;
+    /**
+     * Optional memory provider used to seed stores and drive realtime updates.
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/memory
+     */
     readonly memory: MemoryDBProvider<I> | undefined;
+    /**
+     * Create a cache of stores for a single collection.
+     *
+     * @param collection The collection to cache stores for.
+     * @param provider The database provider the stores fetch from.
+     * @param memory Optional memory provider used to seed stores and drive realtime updates.
+     * @example new CollectionCache(collection, provider)
+     */
     constructor(collection: Collection<string, I, T>, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
-    /** Get (or create) the `ItemStore` for the given id. */
+    /**
+     * Get (or create) the `ItemStore` for the given id.
+     *
+     * @param id The ID of the item to get a store for.
+     * @returns The cached (or newly created) `ItemStore` for the id.
+     * @example cache.getItem("abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/getItem
+     */
     getItem(id: I): ItemStore<I, T>;
-    /** Get (or create) the `QueryStore` for the given query. */
+    /**
+     * Get (or create) the `QueryStore` for the given query.
+     *
+     * @param query The query to get a store for.
+     * @returns The cached (or newly created) `QueryStore` for the query.
+     * @example cache.getQuery(query)
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/getQuery
+     */
     getQuery(query: Query<Item<I, T>>): QueryStore<I, T>;
-    /** Refresh a specific item store. */
+    /**
+     * Refresh a specific item store.
+     *
+     * @param id The ID of the item store to refresh.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshItem("abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshItem
+     */
     refreshItem(id: I, maxAge?: number): Promise<void>;
-    /** Refresh every cached item store. */
+    /**
+     * Refresh every cached item store.
+     *
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every item store has refreshed.
+     * @example await cache.refreshItems()
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshItems
+     */
     refreshItems(maxAge?: number): Promise<void>;
-    /** Refresh a specific query store. */
+    /**
+     * Refresh a specific query store.
+     *
+     * @param query The query whose store should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshQuery(query)
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshQuery
+     */
     refreshQuery(query: Query<Item<I, T>>, maxAge?: number): Promise<void>;
-    /** Refresh every cached query store. */
+    /**
+     * Refresh every cached query store.
+     *
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every query store has refreshed.
+     * @example await cache.refreshQueries()
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshQueries
+     */
     refreshQueries(maxAge?: number): Promise<void>;
-    /** Refresh every cached store (items and queries). */
+    /**
+     * Refresh every cached store (items and queries).
+     *
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every store has refreshed.
+     * @example await cache.refreshAll()
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshAll
+     */
     refreshAll(maxAge?: number): Promise<void>;
     private _queryKey;
     [Symbol.asyncDispose](): Promise<void>;

package/db/cache/CollectionCache.js

@@ -7,44 +7,120 @@ import { QueryStore } from "../store/QueryStore.js";
  * Cache of `ItemStore` and `QueryStore` objects for a single collection.
  * - Use `getItem(id)` to retrieve or create the `ItemStore` for a given id.
  * - Use `getQuery(query)` to retrieve or create the `QueryStore` for a given query.
+ *
+ * @example
+ *  const cache = new CollectionCache(collection, provider);
+ *  const store = cache.getItem("abc");
+ * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache
  */
 export class CollectionCache {
     _items = new Map();
     _queries = new Map();
+    /**
+     * The collection these cached stores belong to.
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/collection
+     */
     collection;
+    /**
+     * The database provider the cached stores fetch from.
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/provider
+     */
     provider;
+    /**
+     * Optional memory provider used to seed stores and drive realtime updates.
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/memory
+     */
     memory;
+    /**
+     * Create a cache of stores for a single collection.
+     *
+     * @param collection The collection to cache stores for.
+     * @param provider The database provider the stores fetch from.
+     * @param memory Optional memory provider used to seed stores and drive realtime updates.
+     * @example new CollectionCache(collection, provider)
+     */
     constructor(collection, provider, memory) {
         this.collection = collection;
         this.provider = provider;
         this.memory = memory;
     }
-    /** Get (or create) the `ItemStore` for the given id. */
+    /**
+     * Get (or create) the `ItemStore` for the given id.
+     *
+     * @param id The ID of the item to get a store for.
+     * @returns The cached (or newly created) `ItemStore` for the id.
+     * @example cache.getItem("abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/getItem
+     */
     getItem(id) {
         return this._items.get(id) || setMapItem(this._items, id, new ItemStore(this.collection, id, this.provider, this.memory));
     }
-    /** Get (or create) the `QueryStore` for the given query. */
+    /**
+     * Get (or create) the `QueryStore` for the given query.
+     *
+     * @param query The query to get a store for.
+     * @returns The cached (or newly created) `QueryStore` for the query.
+     * @example cache.getQuery(query)
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/getQuery
+     */
     getQuery(query) {
         const key = this._queryKey(query);
         return this._queries.get(key) || setMapItem(this._queries, key, new QueryStore(this.collection, query, this.provider, this.memory));
     }
-    /** Refresh a specific item store. */
+    /**
+     * Refresh a specific item store.
+     *
+     * @param id The ID of the item store to refresh.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshItem("abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshItem
+     */
     async refreshItem(id, maxAge) {
         await this._items.get(id)?.refresh(maxAge);
     }
-    /** Refresh every cached item store. */
+    /**
+     * Refresh every cached item store.
+     *
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every item store has refreshed.
+     * @example await cache.refreshItems()
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshItems
+     */
     async refreshItems(maxAge) {
         await awaitValues(...this._items.values().map(store => store.refresh(maxAge)));
     }
-    /** Refresh a specific query store. */
+    /**
+     * Refresh a specific query store.
+     *
+     * @param query The query whose store should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshQuery(query)
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshQuery
+     */
     async refreshQuery(query, maxAge) {
         await this._queries.get(this._queryKey(query))?.refresh(maxAge);
     }
-    /** Refresh every cached query store. */
+    /**
+     * Refresh every cached query store.
+     *
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every query store has refreshed.
+     * @example await cache.refreshQueries()
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshQueries
+     */
     async refreshQueries(maxAge) {
         await awaitValues(...this._queries.values().map(store => store.refresh(maxAge)));
     }
-    /** Refresh every cached store (items and queries). */
+    /**
+     * Refresh every cached store (items and queries).
+     *
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every store has refreshed.
+     * @example await cache.refreshAll()
+     * @see https://dhoulb.github.io/shelving/db/cache/CollectionCache/CollectionCache/refreshAll
+     */
     async refreshAll(maxAge) {
         await awaitValues(this.refreshItems(maxAge), this.refreshQueries(maxAge));
     }

package/db/cache/DBCache.d.ts

@@ -11,28 +11,113 @@ import { CollectionCache } from "./CollectionCache.js";
  * Cache of `CollectionCache` objects for multiple collections.
  * - Use `get(collection)` to retrieve or create the `CollectionCache` for a given collection,
  *   then `getItem(id)` / `getQuery(query)` on that to get a specific store.
+ * - If the provider chain contains a `CacheDBProvider`, its memory is reused so stores can seed synchronously.
+ *
+ * @example
+ *  const cache = new DBCache(provider);
+ *  const store = cache.getItem(collection, "abc");
+ * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache
  */
 export declare class DBCache<I extends Identifier = Identifier, T extends Data = Data> implements AsyncDisposable {
     private readonly _collections;
+    /**
+     * The database provider the cached stores fetch from.
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/provider
+     */
     readonly provider: DBProvider<I, T>;
+    /**
+     * Memory provider reused from the provider chain to seed stores synchronously, if available.
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/memory
+     */
     readonly memory: MemoryDBProvider<I, T> | undefined;
+    /**
+     * Create a cache of collection caches for a database provider.
+     *
+     * @param provider The database provider the cached stores fetch from.
+     * @example new DBCache(provider)
+     */
     constructor(provider: DBProvider<I, T>);
     private _get;
-    /** Get (or create) the `CollectionCache` for the given collection. */
+    /**
+     * Get (or create) the `CollectionCache` for the given collection.
+     *
+     * @param collection The collection to get a cache for.
+     * @returns The cached (or newly created) `CollectionCache` for the collection.
+     * @example cache.get(collection)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/get
+     */
     get<II extends I, TT extends T>(collection: Collection<string, II, TT>): CollectionCache<II, TT>;
-    /** Get (or create) an `ItemStore` for a collection/id in one hop. */
+    /**
+     * Get (or create) an `ItemStore` for a collection/id in one hop.
+     *
+     * @param collection The collection the item lives in.
+     * @param id The ID of the item to get a store for.
+     * @returns The cached (or newly created) `ItemStore`.
+     * @example cache.getItem(collection, "abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/getItem
+     */
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): ItemStore<II, TT>;
-    /** Get (or create) a `QueryStore` for a collection/query in one hop. */
+    /**
+     * Get (or create) a `QueryStore` for a collection/query in one hop.
+     *
+     * @param collection The collection the query runs against.
+     * @param query The query to get a store for.
+     * @returns The cached (or newly created) `QueryStore`.
+     * @example cache.getQuery(collection, query)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/getQuery
+     */
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): QueryStore<II, TT>;
-    /** Refresh a specific item store for a collection. */
+    /**
+     * Refresh a specific item store for a collection.
+     *
+     * @param collection The collection the item lives in.
+     * @param id The ID of the item store to refresh.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshItem(collection, "abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshItem
+     */
     refreshItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, maxAge?: number): Promise<void>;
-    /** Refresh every cached item store for a collection. */
+    /**
+     * Refresh every cached item store for a collection.
+     *
+     * @param collection The collection whose item stores should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every item store has refreshed.
+     * @example await cache.refreshItems(collection)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshItems
+     */
     refreshItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
-    /** Refresh a specific query store for a collection. */
+    /**
+     * Refresh a specific query store for a collection.
+     *
+     * @param collection The collection the query runs against.
+     * @param query The query whose store should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshQuery(collection, query)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshQuery
+     */
     refreshQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, maxAge?: number): Promise<void>;
-    /** Refresh every cached query store for a collection. */
+    /**
+     * Refresh every cached query store for a collection.
+     *
+     * @param collection The collection whose query stores should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every query store has refreshed.
+     * @example await cache.refreshQueries(collection)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshQueries
+     */
     refreshQueries<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
-    /** Refresh every cached store (items and queries) for a collection. */
+    /**
+     * Refresh every cached store (items and queries) for a collection.
+     *
+     * @param collection The collection whose stores should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every store has refreshed.
+     * @example await cache.refreshAll(collection)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshAll
+     */
     refreshAll<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/cache/DBCache.js

@@ -7,11 +7,31 @@ import { CollectionCache } from "./CollectionCache.js";
  * Cache of `CollectionCache` objects for multiple collections.
  * - Use `get(collection)` to retrieve or create the `CollectionCache` for a given collection,
  *   then `getItem(id)` / `getQuery(query)` on that to get a specific store.
+ * - If the provider chain contains a `CacheDBProvider`, its memory is reused so stores can seed synchronously.
+ *
+ * @example
+ *  const cache = new DBCache(provider);
+ *  const store = cache.getItem(collection, "abc");
+ * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache
  */
 export class DBCache {
     _collections = new Map();
+    /**
+     * The database provider the cached stores fetch from.
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/provider
+     */
     provider;
+    /**
+     * Memory provider reused from the provider chain to seed stores synchronously, if available.
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/memory
+     */
     memory;
+    /**
+     * Create a cache of collection caches for a database provider.
+     *
+     * @param provider The database provider the cached stores fetch from.
+     * @example new DBCache(provider)
+     */
     constructor(provider) {
         this.provider = provider;
         // If the provider chain contains a `CacheDBProvider`, reuse its memory so we can seed stores synchronously.
@@ -23,31 +43,89 @@ export class DBCache {
     get(collection) {
         return this._get(collection) || setMapItem(this._collections, collection, new CollectionCache(collection, this.provider, this.memory));
     }
-    /** Get (or create) an `ItemStore` for a collection/id in one hop. */
+    /**
+     * Get (or create) an `ItemStore` for a collection/id in one hop.
+     *
+     * @param collection The collection the item lives in.
+     * @param id The ID of the item to get a store for.
+     * @returns The cached (or newly created) `ItemStore`.
+     * @example cache.getItem(collection, "abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/getItem
+     */
     getItem(collection, id) {
         return this.get(collection).getItem(id);
     }
-    /** Get (or create) a `QueryStore` for a collection/query in one hop. */
+    /**
+     * Get (or create) a `QueryStore` for a collection/query in one hop.
+     *
+     * @param collection The collection the query runs against.
+     * @param query The query to get a store for.
+     * @returns The cached (or newly created) `QueryStore`.
+     * @example cache.getQuery(collection, query)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/getQuery
+     */
     getQuery(collection, query) {
         return this.get(collection).getQuery(query);
     }
-    /** Refresh a specific item store for a collection. */
+    /**
+     * Refresh a specific item store for a collection.
+     *
+     * @param collection The collection the item lives in.
+     * @param id The ID of the item store to refresh.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshItem(collection, "abc")
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshItem
+     */
     async refreshItem(collection, id, maxAge) {
         await this._get(collection)?.refreshItem(id, maxAge);
     }
-    /** Refresh every cached item store for a collection. */
+    /**
+     * Refresh every cached item store for a collection.
+     *
+     * @param collection The collection whose item stores should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every item store has refreshed.
+     * @example await cache.refreshItems(collection)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshItems
+     */
     async refreshItems(collection, maxAge) {
         await this._get(collection)?.refreshItems(maxAge);
     }
-    /** Refresh a specific query store for a collection. */
+    /**
+     * Refresh a specific query store for a collection.
+     *
+     * @param collection The collection the query runs against.
+     * @param query The query whose store should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once the refresh has completed.
+     * @example await cache.refreshQuery(collection, query)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshQuery
+     */
     async refreshQuery(collection, query, maxAge) {
         await this._get(collection)?.refreshQuery(query, maxAge);
     }
-    /** Refresh every cached query store for a collection. */
+    /**
+     * Refresh every cached query store for a collection.
+     *
+     * @param collection The collection whose query stores should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every query store has refreshed.
+     * @example await cache.refreshQueries(collection)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshQueries
+     */
     async refreshQueries(collection, maxAge) {
         await this._get(collection)?.refreshQueries(maxAge);
     }
-    /** Refresh every cached store (items and queries) for a collection. */
+    /**
+     * Refresh every cached store (items and queries) for a collection.
+     *
+     * @param collection The collection whose stores should be refreshed.
+     * @param maxAge Maximum age in milliseconds of cached data that may be reused instead of refetching.
+     * @returns Promise that resolves once every store has refreshed.
+     * @example await cache.refreshAll(collection)
+     * @see https://dhoulb.github.io/shelving/db/cache/DBCache/DBCache/refreshAll
+     */
     async refreshAll(collection, maxAge) {
         await this._get(collection)?.refreshAll(maxAge);
     }

package/db/collection/Collection.d.ts

@@ -4,38 +4,126 @@ import type { Schema, Schemas } from "../../schema/Schema.js";
 import type { ImmutableArray } from "../../util/array.js";
 import type { Data } from "../../util/data.js";
 import type { Identifier, Item, Items, OptionalItem } from "../../util/item.js";
-/** Default identifier schema (integer). */
+/**
+ * Default identifier schema (integer) used when a collection doesn't supply its own.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/ID
+ */
 export declare const ID: NumberSchema;
-/** Declarative definition of a database collection/table. */
+/**
+ * Declarative definition of a database collection/table.
+ *
+ * - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
+ * - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
+ *
+ * @example
+ *  const users = new Collection("users", ID, { name: STRING, age: NUMBER });
+ *  users.validate({ name: "Dave", age: 40 }); // Validates item data.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection
+ */
 export declare class Collection<N extends string = string, I extends Identifier = Identifier, T extends Data = Data> extends DataSchema<T> {
-    /** Collection name (used as the table/collection key). */
+    /**
+     * Collection name (used as the table/collection key).
+     *
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/name
+     */
     readonly name: N;
-    /** Schema for the identifier type. */
+    /**
+     * Schema for the identifier type.
+     *
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/id
+     */
     readonly id: Schema<I>;
-    /** Schema for a complete item (id + data). */
+    /**
+     * Schema for a complete item (id + data).
+     *
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/item
+     */
     readonly item: DataSchema<Item<I, T>>;
+    /**
+     * Create a new `Collection`.
+     *
+     * @param name Collection name used as the table/collection key.
+     * @param id Schema for the identifier type.
+     * @param data Data schema, or the `Schemas` props used to construct one.
+     */
     constructor(name: N, id: Schema<I>, data: Schemas<T> | DataSchema<T>);
+    /**
+     * Convert this collection to its string name.
+     *
+     * @returns The collection name.
+     * @example `${users}` // "users"
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/toString
+     */
     toString(): string;
 }
-/** Shortcut factory for creating a Collection. */
+/**
+ * Create a `Collection` from a name, an identifier schema, and a data schema.
+ *
+ * *Factory for `Collection`.*
+ *
+ * @param name Collection name used as the table/collection key.
+ * @param id Schema for the identifier type.
+ * @param data Data schema, or the `Schemas` props used to construct one.
+ * @returns A new `Collection` instance.
+ * @example COLLECTION("users", ID, { name: STRING, age: NUMBER }) // Collection<"users", number, { name: string; age: number }>
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/COLLECTION
+ */
 export declare function COLLECTION<K extends string, I extends Identifier, T extends Data>(name: K, id: Schema<I>, data: Schemas<T> | DataSchema<T>): Collection<K, I, T>;
-/** Extract the string name from a `Collection` instance. */
+/**
+ * Extract the string name from a `Collection` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/CollectionName
+ */
 export type CollectionName<C extends Collection> = C extends Collection<infer N, infer _I, infer _T> ? N : never;
-/** Extract the `Identifier` type from a `Collection` instance. */
+/**
+ * Extract the `Identifier` type from a `Collection` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/CollectionIdentifier
+ */
 export type CollectionIdentifier<C extends Collection> = C extends Collection<infer _N, infer I, infer _T> ? I : never;
-/** Extract the `Data` type from a `Collection` instance. */
+/**
+ * Extract the `Data` type from a `Collection` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/CollectionData
+ */
 export type CollectionData<C extends Collection> = C extends Collection<infer _N, infer _I, infer T> ? T : never;
-/** Extract the `Item` type from a `Collection` instance. */
+/**
+ * Extract the `Item` type from a `Collection` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/CollectionItem
+ */
 export type CollectionItem<C extends Collection> = Item<CollectionIdentifier<C>, CollectionData<C>>;
-/** Extract the optional (possibly undefined) `Item` type from a `Collection` instance. */
+/**
+ * Extract the optional (possibly undefined) `Item` type from a `Collection` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/OptionalCollectionItem
+ */
 export type OptionalCollectionItem<C extends Collection> = OptionalItem<CollectionIdentifier<C>, CollectionData<C>>;
-/** Extract the array of `Item` types from a `Collection` instance. */
+/**
+ * Extract the array of `Item` types from a `Collection` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/CollectionItems
+ */
 export type CollectionItems<C extends Collection> = Items<CollectionIdentifier<C>, CollectionData<C>>;
-/** A readonly array of Collection instances, possibly with a standardised `Identifier` and `Data` types. */
+/**
+ * A readonly array of `Collection` instances, optionally narrowed to a standardised `Identifier` and `Data` type.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collections
+ */
 export type Collections<I extends Identifier = Identifier, D extends Data = Data> = ImmutableArray<Collection<string, I, D>>;
-/** Extract the union of string collection names from a `Collections` type. */
+/**
+ * Extract the union of string collection names from a `Collections` type.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/CollectionNames
+ */
 export type CollectionNames<C extends Collections> = C[number]["name"];
-/** Convert a `Collections` array type to a Database-style object mapping in `{ name: data }` format. */
+/**
+ * Convert a `Collections` array type to a database-style object mapping in `{ name: data }` format.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/CollectionsDatabase
+ */
 export type CollectionsDatabase<C extends Collections> = {
     [E in C[number] as E extends Collection<infer N, Identifier, Data> ? N : never]: E extends Collection<string, Identifier, infer T> ? T : never;
 };