shelving 1.271.3 → 1.272.0

package/cloudflare/CloudflareKVProvider.d.ts

@@ -16,9 +16,9 @@ import type { KVNamespace } from "./types.js";
  * - ID generation: `addItem()` generates a UUID v4 identifier automatically.
  *
  * ### Not supported
- * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
+ * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnsupportedError`.
  *   KV has no change feed or push notification mechanism.
- * - **Updates:** `updateItem()` and `updateQuery()` throw `UnimplementedError`.
+ * - **Updates:** `updateItem()` and `updateQuery()` throw `UnsupportedError`.
  * - **Collection queries:** `getQuery()`, `setQuery()`, `deleteQuery()`, and `countQuery()` are not supported.
  *   KV does not expose efficient filtering, sorting, or collection scans, so this provider avoids the old "read everything and filter in memory" behavior.
  *
@@ -33,22 +33,22 @@ export declare class CloudflareKVProvider<I extends string = string, T extends D
     private readonly _kv;
     constructor(kv: KVNamespace);
     getItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
-    /** Not supported — KV has no change feed, so this throws `UnimplementedError`. */
+    /** Not supported — KV has no change feed, so this throws `UnsupportedError`. */
     getItemSequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _id: II): OptionalItemSequence<II, TT>;
     /** Generates a UUID v4 identifier for the new item. */
     addItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, data: TT): Promise<II>;
     setItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
-    /** Not supported — KV cannot apply partial updates, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot apply partial updates, so this throws `UnsupportedError`. */
     updateItem<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _id: II, _updates: Updates<Item<II, TT>>): Promise<void>;
     deleteItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II): Promise<void>;
-    /** Not supported — KV cannot filter, sort, or scan collections, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot filter, sort, or scan collections, so this throws `UnsupportedError`. */
     getQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
-    /** Not supported — KV has no change feed, so this throws `UnimplementedError`. */
+    /** Not supported — KV has no change feed, so this throws `UnsupportedError`. */
     getQuerySequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
-    /** Not supported — KV cannot run collection queries, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot run collection queries, so this throws `UnsupportedError`. */
     setQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>, _data: TT): Promise<void>;
-    /** Not supported — KV supports neither updates nor collection queries, so this throws `UnimplementedError`. */
+    /** Not supported — KV supports neither updates nor collection queries, so this throws `UnsupportedError`. */
     updateQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>, _updates: Updates<TT>): Promise<void>;
-    /** Not supported — KV cannot run collection queries, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot run collection queries, so this throws `UnsupportedError`. */
     deleteQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>): Promise<void>;
 }

package/cloudflare/CloudflareKVProvider.js

@@ -1,5 +1,5 @@
 import { DBProvider } from "../db/provider/DBProvider.js";
-import { UnimplementedError } from "../error/UnimplementedError.js";
+import { UnsupportedError } from "../error/UnsupportedError.js";
 import { getItem } from "../util/item.js";
 import { randomUUID } from "../util/uuid.js";
 /**
@@ -13,9 +13,9 @@ import { randomUUID } from "../util/uuid.js";
  * - ID generation: `addItem()` generates a UUID v4 identifier automatically.
  *
  * ### Not supported
- * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
+ * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnsupportedError`.
  *   KV has no change feed or push notification mechanism.
- * - **Updates:** `updateItem()` and `updateQuery()` throw `UnimplementedError`.
+ * - **Updates:** `updateItem()` and `updateQuery()` throw `UnsupportedError`.
  * - **Collection queries:** `getQuery()`, `setQuery()`, `deleteQuery()`, and `countQuery()` are not supported.
  *   KV does not expose efficient filtering, sorting, or collection scans, so this provider avoids the old "read everything and filter in memory" behavior.
  *
@@ -37,9 +37,9 @@ export class CloudflareKVProvider extends DBProvider {
         if (data)
             return getItem(id, data);
     }
-    /** Not supported — KV has no change feed, so this throws `UnimplementedError`. */
+    /** Not supported — KV has no change feed, so this throws `UnsupportedError`. */
     getItemSequence(_collection, _id) {
-        throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
+        throw new UnsupportedError("CloudflareKVProvider does not support realtime subscriptions");
     }
     /** Generates a UUID v4 identifier for the new item. */
     async addItem({ name }, data) {
@@ -50,32 +50,32 @@ export class CloudflareKVProvider extends DBProvider {
     async setItem({ name }, id, data) {
         await this._kv.put(_getKey(name, id), JSON.stringify(data));
     }
-    /** Not supported — KV cannot apply partial updates, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot apply partial updates, so this throws `UnsupportedError`. */
     async updateItem(_collection, _id, _updates) {
-        throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
+        throw new UnsupportedError("CloudflareKVProvider does not support updates to items");
     }
     async deleteItem({ name }, id) {
         await this._kv.delete(_getKey(name, id));
     }
-    /** Not supported — KV cannot filter, sort, or scan collections, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot filter, sort, or scan collections, so this throws `UnsupportedError`. */
     async getQuery(_collection, _query) {
-        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
+        throw new UnsupportedError("CloudflareKVProvider does not support querying items");
     }
-    /** Not supported — KV has no change feed, so this throws `UnimplementedError`. */
+    /** Not supported — KV has no change feed, so this throws `UnsupportedError`. */
     getQuerySequence(_collection, _query) {
-        throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
+        throw new UnsupportedError("CloudflareKVProvider does not support realtime subscriptions");
     }
-    /** Not supported — KV cannot run collection queries, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot run collection queries, so this throws `UnsupportedError`. */
     async setQuery(_collection, _query, _data) {
-        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
+        throw new UnsupportedError("CloudflareKVProvider does not support querying items");
     }
-    /** Not supported — KV supports neither updates nor collection queries, so this throws `UnimplementedError`. */
+    /** Not supported — KV supports neither updates nor collection queries, so this throws `UnsupportedError`. */
     async updateQuery(_collection, _query, _updates) {
-        throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
+        throw new UnsupportedError("CloudflareKVProvider does not support updates to items");
     }
-    /** Not supported — KV cannot run collection queries, so this throws `UnimplementedError`. */
+    /** Not supported — KV cannot run collection queries, so this throws `UnsupportedError`. */
     async deleteQuery(_collection, _query) {
-        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
+        throw new UnsupportedError("CloudflareKVProvider does not support querying items");
     }
 }
 function _getKey(collection, id) {

package/db/migrate/DBMigrator.d.ts

@@ -18,7 +18,7 @@ export declare abstract class DBMigrator<T extends DBProvider = DBProvider> {
      * Bring the provider's storage into line with the given collection schemas.
      *
      * @param collections The collections whose schemas the storage should match.
-     * @throws `UnimplementedError` if a schema feature can't be represented by the backend.
+     * @throws `UnsupportedError` if a schema feature can't be represented by the backend.
      * @example await migrator.migrate(users, posts)
      * @see https://shelving.cc/db/DBMigrator/migrate
      */

package/db/migrate/SQLMigrator.js

@@ -1,4 +1,4 @@
-import { UnimplementedError } from "../../error/UnimplementedError.js";
+import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { ArraySchema } from "../../schema/ArraySchema.js";
 import { BooleanSchema } from "../../schema/BooleanSchema.js";
 import { ChoiceSchema } from "../../schema/ChoiceSchema.js";
@@ -97,12 +97,12 @@ export class SQLMigrator extends DBMigrator {
     }
     getAddColumnQuery(tableName, column) {
         if (column.name === "id")
-            throw new UnimplementedError(`Cannot add primary key column to existing table "${tableName}"`);
+            throw new UnsupportedError(`Cannot add primary key column to existing table "${tableName}"`);
         return `ALTER TABLE ${this.quoteIdentifier(tableName)} ADD COLUMN ${this.getTableColumnDefinition(column)};`;
     }
     getDropColumnQuery(tableName, columnName) {
         if (columnName === "id")
-            throw new UnimplementedError(`Cannot drop primary key column from existing table "${tableName}"`);
+            throw new UnsupportedError(`Cannot drop primary key column from existing table "${tableName}"`);
         return `ALTER TABLE ${this.quoteIdentifier(tableName)} DROP COLUMN ${this.quoteIdentifier(columnName)};`;
     }
     getTableMigrations(collection, table) {
@@ -129,7 +129,7 @@ export class SQLMigrator extends DBMigrator {
         const schema = _getColumnSchema(collection, key);
         const definition = this.definition(schema);
         if (!definition)
-            throw new UnimplementedError(`Cannot generate SQL column for "${key}"`, { received: schema });
+            throw new UnsupportedError(`Cannot generate SQL column for "${key}"`, { received: schema });
         return { name: column, statement: this.getGeneratedColumnDefinition(column, path, definition) };
     }
     isSameColumn(from, to) {
@@ -180,10 +180,10 @@ function _getColumnSchema(collection, key) {
     for (const part of key.split(".")) {
         const current = _unwrapSchema(schema);
         if (!(current instanceof DataSchema))
-            throw new UnimplementedError(`Cannot resolve schema path "${key}"`);
+            throw new UnsupportedError(`Cannot resolve schema path "${key}"`);
         const next = current.props[part];
         if (!next)
-            throw new UnimplementedError(`Cannot resolve schema path "${key}"`);
+            throw new UnsupportedError(`Cannot resolve schema path "${key}"`);
         schema = next;
     }
     return schema;

package/db/migrate/SQLiteMigrator.js

@@ -1,4 +1,4 @@
-import { UnimplementedError } from "../../error/UnimplementedError.js";
+import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { ChoiceSchema } from "../../schema/ChoiceSchema.js";
 import { DateSchema } from "../../schema/DateSchema.js";
 import { NumberSchema } from "../../schema/NumberSchema.js";
@@ -47,7 +47,7 @@ export class SQLiteMigrator extends SQLMigrator {
         if (id instanceof NumberSchema) {
             if (id.step === 1)
                 return "INTEGER PRIMARY KEY";
-            throw new UnimplementedError("SQLiteMigrator only supports string and integer identifiers", { received: id });
+            throw new UnsupportedError("SQLiteMigrator only supports string and integer identifiers", { received: id });
         }
         if (id instanceof ChoiceSchema || id instanceof DateSchema)
             return "TEXT PRIMARY KEY";
@@ -62,7 +62,7 @@ export class SQLiteMigrator extends SQLMigrator {
     }
     getAlterColumnQueries(tableName, from, to) {
         if (from.name === "id" || from.name === "data") {
-            throw new UnimplementedError(`Cannot alter SQLite column "${from.name}" in existing table "${tableName}"`);
+            throw new UnsupportedError(`Cannot alter SQLite column "${from.name}" in existing table "${tableName}"`);
         }
         return super.getAlterColumnQueries(tableName, from, to);
     }

package/db/provider/SQLProvider.d.ts

@@ -19,7 +19,7 @@ export interface SQLFragment {
  *
  * - Subclasses implement `exec()` to run a query against a concrete database (e.g. SQLite, PostgreSQL).
  * - The `sql*` helpers build composable `SQLFragment` objects so dialect differences can be overridden.
- * - Realtime subscriptions are unsupported and throw `UnimplementedError`.
+ * - Realtime subscriptions are unsupported and throw `UnsupportedError`.
  *
  * @see https://shelving.cc/db/SQLProvider
  */
@@ -34,7 +34,7 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
      */
     abstract exec<X extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<ImmutableArray<X>>;
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
-    /** Unsupported by SQL providers — always throws `UnimplementedError`. */
+    /** Unsupported by SQL providers — always throws `UnsupportedError`. */
     getItemSequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _id: II): OptionalItemSequence<II, TT>;
     /** Insert via `INSERT ... RETURNING`; throws `RequiredError` if no id comes back. */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
@@ -43,7 +43,7 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
     countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
-    /** Unsupported by SQL providers — always throws `UnimplementedError`. */
+    /** Unsupported by SQL providers — always throws `UnsupportedError`. */
     getQuerySequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
@@ -70,7 +70,7 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
      * - Base implementation only supports flat (single-segment) keys; subclasses override for nested JSON paths.
      *
      * @param key The key segments identifying the column (and any nested path).
-     * @throws `UnimplementedError` if the key is nested (multi-segment).
+     * @throws `UnsupportedError` if the key is nested (multi-segment).
      * @example this.sqlExtract(["name"]); // "name"
      * @see https://shelving.cc/db/SQLProvider/sqlExtract
      */
@@ -105,11 +105,11 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
     /**
      * Define an SQL fragment for a single update action.
      * - Handles flat `set` and `sum` only (single-segment key).
-     * - Nested keys (multi-segment) and `with`/`omit` actions throw `UnimplementedError`.
+     * - Nested keys (multi-segment) and `with`/`omit` actions throw `UnsupportedError`.
      * - Subclasses should override to support nested keys and array mutation actions.
      *
      * @param update The update action (`action`, `key`, `value`) to convert.
-     * @throws `UnimplementedError` if the key is nested or the action is unsupported.
+     * @throws `UnsupportedError` if the key is nested or the action is unsupported.
      * @example this.sqlUpdate({ action: "set", key: ["a"], value: 1 }); // "a" = 1
      * @see https://shelving.cc/db/SQLProvider/sqlUpdate
      */
@@ -144,7 +144,7 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
      * Define an SQL fragment for a single filter clause on a column, e.g. `x = 1` or `x IN (1, 2)`.
      *
      * @param filter The filter (`key`, `operator`, `value`) to translate.
-     * @throws `UnimplementedError` if the operator is unsupported.
+     * @throws `UnsupportedError` if the operator is unsupported.
      * @example this.sqlFilter({ key: ["x"], operator: "is", value: 1 }); // "x" = 1
      * @see https://shelving.cc/db/SQLProvider/sqlFilter
      */
@@ -152,10 +152,10 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
     /**
      * Define an SQL fragment for an `ORDER BY` clause, e.g. ` ORDER BY "a" ASC, "b" DESC`.
      * - Returns an empty fragment when the query has no orders.
-     * - Nested keys (multi-segment) throw `UnimplementedError`.
+     * - Nested keys (multi-segment) throw `UnsupportedError`.
      *
      * @param query The query whose orders become the `ORDER BY` clause.
-     * @throws `UnimplementedError` if an order key is nested (multi-segment).
+     * @throws `UnsupportedError` if an order key is nested (multi-segment).
      * @example this.sqlOrder(query); // ORDER BY "a" ASC
      * @see https://shelving.cc/db/SQLProvider/sqlOrder
      */

package/db/provider/SQLProvider.js

@@ -1,5 +1,5 @@
 import { RequiredError } from "../../error/RequiredError.js";
-import { UnimplementedError } from "../../error/UnimplementedError.js";
+import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { getQueryFilters, getQueryLimit, getQueryOrders } from "../../util/query.js";
 import { getUpdates } from "../../util/update.js";
 import { DBProvider } from "./DBProvider.js";
@@ -8,7 +8,7 @@ import { DBProvider } from "./DBProvider.js";
  *
  * - Subclasses implement `exec()` to run a query against a concrete database (e.g. SQLite, PostgreSQL).
  * - The `sql*` helpers build composable `SQLFragment` objects so dialect differences can be overridden.
- * - Realtime subscriptions are unsupported and throw `UnimplementedError`.
+ * - Realtime subscriptions are unsupported and throw `UnsupportedError`.
  *
  * @see https://shelving.cc/db/SQLProvider
  */
@@ -21,9 +21,9 @@ export class SQLProvider extends DBProvider {
 		`;
         return rows[0];
     }
-    /** Unsupported by SQL providers — always throws `UnimplementedError`. */
+    /** Unsupported by SQL providers — always throws `UnsupportedError`. */
     getItemSequence(_collection, _id) {
-        throw new UnimplementedError(`SQLProvider does not support realtime subscriptions`);
+        throw new UnsupportedError(`SQLProvider does not support realtime subscriptions`);
     }
     /** Insert via `INSERT ... RETURNING`; throws `RequiredError` if no id comes back. */
     async addItem(collection, data) {
@@ -65,9 +65,9 @@ export class SQLProvider extends DBProvider {
 			${query ? this.sqlClauses(query) : this.sql ``}
 		`;
     }
-    /** Unsupported by SQL providers — always throws `UnimplementedError`. */
+    /** Unsupported by SQL providers — always throws `UnsupportedError`. */
     getQuerySequence(_collection, _query) {
-        throw new UnimplementedError(`SQLProvider does not support realtime subscriptions`);
+        throw new UnsupportedError(`SQLProvider does not support realtime subscriptions`);
     }
     async setQuery(collection, query, data) {
         await this.exec `UPDATE ${this.sqlIdentifier(collection.name)} SET ${this.sqlSetters(data)}${this.sqlClauses(query)}`;
@@ -104,13 +104,13 @@ export class SQLProvider extends DBProvider {
      * - Base implementation only supports flat (single-segment) keys; subclasses override for nested JSON paths.
      *
      * @param key The key segments identifying the column (and any nested path).
-     * @throws `UnimplementedError` if the key is nested (multi-segment).
+     * @throws `UnsupportedError` if the key is nested (multi-segment).
      * @example this.sqlExtract(["name"]); // "name"
      * @see https://shelving.cc/db/SQLProvider/sqlExtract
      */
     sqlExtract(key) {
         if (key.length > 1)
-            throw new UnimplementedError("SQLProvider does not support nested filter keys");
+            throw new UnsupportedError("SQLProvider does not support nested filter keys");
         return this.sqlIdentifier(key[0]);
     }
     /**
@@ -151,23 +151,23 @@ export class SQLProvider extends DBProvider {
     /**
      * Define an SQL fragment for a single update action.
      * - Handles flat `set` and `sum` only (single-segment key).
-     * - Nested keys (multi-segment) and `with`/`omit` actions throw `UnimplementedError`.
+     * - Nested keys (multi-segment) and `with`/`omit` actions throw `UnsupportedError`.
      * - Subclasses should override to support nested keys and array mutation actions.
      *
      * @param update The update action (`action`, `key`, `value`) to convert.
-     * @throws `UnimplementedError` if the key is nested or the action is unsupported.
+     * @throws `UnsupportedError` if the key is nested or the action is unsupported.
      * @example this.sqlUpdate({ action: "set", key: ["a"], value: 1 }); // "a" = 1
      * @see https://shelving.cc/db/SQLProvider/sqlUpdate
      */
     sqlUpdate({ action, key, value }) {
         if (key.length > 1)
-            throw new UnimplementedError("SQLProvider does not support nested update keys");
+            throw new UnsupportedError("SQLProvider does not support nested update keys");
         const column = this.sqlIdentifier(key[0]);
         if (action === "set")
             return this.sql `${column} = ${value}`;
         if (action === "sum")
             return this.sql `${column} = ${column} + ${value}`;
-        throw new UnimplementedError(`SQLProvider does not support "${action}" updates`);
+        throw new UnsupportedError(`SQLProvider does not support "${action}" updates`);
     }
     /**
      * Define an SQL fragment for `VALUES` syntax, e.g. `("a", "b") VALUES (1, 2)`.
@@ -211,7 +211,7 @@ export class SQLProvider extends DBProvider {
      * Define an SQL fragment for a single filter clause on a column, e.g. `x = 1` or `x IN (1, 2)`.
      *
      * @param filter The filter (`key`, `operator`, `value`) to translate.
-     * @throws `UnimplementedError` if the operator is unsupported.
+     * @throws `UnsupportedError` if the operator is unsupported.
      * @example this.sqlFilter({ key: ["x"], operator: "is", value: 1 }); // "x" = 1
      * @see https://shelving.cc/db/SQLProvider/sqlFilter
      */
@@ -239,15 +239,15 @@ export class SQLProvider extends DBProvider {
             return this.sql `${path} > ${value}`;
         if (operator === "gte")
             return this.sql `${path} >= ${value}`;
-        throw new UnimplementedError(`SQLProvider does not support "${operator}" filters`);
+        throw new UnsupportedError(`SQLProvider does not support "${operator}" filters`);
     }
     /**
      * Define an SQL fragment for an `ORDER BY` clause, e.g. ` ORDER BY "a" ASC, "b" DESC`.
      * - Returns an empty fragment when the query has no orders.
-     * - Nested keys (multi-segment) throw `UnimplementedError`.
+     * - Nested keys (multi-segment) throw `UnsupportedError`.
      *
      * @param query The query whose orders become the `ORDER BY` clause.
-     * @throws `UnimplementedError` if an order key is nested (multi-segment).
+     * @throws `UnsupportedError` if an order key is nested (multi-segment).
      * @example this.sqlOrder(query); // ORDER BY "a" ASC
      * @see https://shelving.cc/db/SQLProvider/sqlOrder
      */

package/error/{UnimplementedError.d.ts → UnsupportedError.d.ts}

@@ -1,12 +1,12 @@
 import { type BaseError, type BaseErrorOptions } from "./BaseError.js";
 /**
- * Error thrown when functionality is called but is not implemented by an interface.
+ * Error thrown when functionality is called but is not supported — by a backend, an environment, or an implementation.
  *
- * @see https://shelving.cc/error/UnimplementedError
+ * @see https://shelving.cc/error/UnsupportedError
  */
-export declare class UnimplementedError extends Error implements BaseError {
+export declare class UnsupportedError extends Error implements BaseError {
     /** Provide additional named contextual data that is relevant to the `Error` instance. */
     readonly [key: string]: unknown;
-    /** @param message Optional human-readable description of the missing implementation. */
+    /** @param message Optional human-readable description of the unsupported functionality. */
     constructor(message?: string, options?: BaseErrorOptions);
 }

package/error/UnsupportedError.js

@@ -0,0 +1,14 @@
+import { setBaseErrorOptions } from "./BaseError.js";
+/**
+ * Error thrown when functionality is called but is not supported — by a backend, an environment, or an implementation.
+ *
+ * @see https://shelving.cc/error/UnsupportedError
+ */
+export class UnsupportedError extends Error {
+    /** @param message Optional human-readable description of the unsupported functionality. */
+    constructor(message, options = {}) {
+        super(message, options);
+        setBaseErrorOptions(UnsupportedError, this, options);
+    }
+}
+UnsupportedError.prototype.name = "UnsupportedError";

package/error/index.d.ts

@@ -5,5 +5,5 @@ export * from "./RequestError.js";
 export * from "./RequiredError.js";
 export * from "./ResponseError.js";
 export * from "./UnexpectedError.js";
-export * from "./UnimplementedError.js";
+export * from "./UnsupportedError.js";
 export * from "./ValueError.js";

package/error/index.js

@@ -5,5 +5,5 @@ export * from "./RequestError.js";
 export * from "./RequiredError.js";
 export * from "./ResponseError.js";
 export * from "./UnexpectedError.js";
-export * from "./UnimplementedError.js";
+export * from "./UnsupportedError.js";
 export * from "./ValueError.js";

package/firestore/lite/FirestoreLiteProvider.d.ts

@@ -10,7 +10,7 @@ import type { Updates } from "../../util/update.js";
  *
  * - Works with the Firebase JS SDK via `firebase/firestore/lite`, which keeps bundle size small.
  * - Does not support offline mode.
- * - Does not support realtime subscriptions: `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
+ * - Does not support realtime subscriptions: `getItemSequence()` and `getQuerySequence()` throw `UnsupportedError`.
  *
  * @see https://shelving.cc/firestore/lite/FirestoreLiteProvider
  */
@@ -24,7 +24,7 @@ export declare class FirestoreLiteProvider<I extends string = string, T extends
     /** Get a Firestore QueryReference for a given query. */
     private _query;
     getItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
-    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnimplementedError`. */
+    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnsupportedError`. */
     getItemSequence<II extends I, TT extends T>(_c: Collection<string, II, TT>, _id: II): OptionalItemSequence<II, TT>;
     addItem<II extends I, TT extends T>(c: Collection<string, II, TT>, data: TT): Promise<II>;
     setItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
@@ -32,7 +32,7 @@ export declare class FirestoreLiteProvider<I extends string = string, T extends
     deleteItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<void>;
     countQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<number>;
     getQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
-    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnimplementedError`. */
+    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnsupportedError`. */
     getQuerySequence<II extends I, TT extends T>(_c: Collection<string, II, TT>, _q?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
     setQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, data: TT): Promise<void>;
     updateQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;

package/firestore/lite/FirestoreLiteProvider.js

@@ -1,6 +1,6 @@
 import { addDoc, arrayRemove, arrayUnion, collection, deleteDoc, doc, documentId, getCount, getDoc, getDocs, increment, limit, orderBy, query, setDoc, updateDoc, where, } from "firebase/firestore/lite";
 import { DBProvider } from "../../db/provider/DBProvider.js";
-import { UnimplementedError } from "../../error/UnimplementedError.js";
+import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { joinDataPath } from "../../util/data.js";
 import { getItem } from "../../util/item.js";
 import { getObject } from "../../util/object.js";
@@ -66,7 +66,7 @@ function _getFieldValue({ key, action, value }) {
  *
  * - Works with the Firebase JS SDK via `firebase/firestore/lite`, which keeps bundle size small.
  * - Does not support offline mode.
- * - Does not support realtime subscriptions: `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
+ * - Does not support realtime subscriptions: `getItemSequence()` and `getQuerySequence()` throw `UnsupportedError`.
  *
  * @see https://shelving.cc/firestore/lite/FirestoreLiteProvider
  */
@@ -92,9 +92,9 @@ export class FirestoreLiteProvider extends DBProvider {
         const snapshot = await getDoc(this._doc(c, id));
         return _getOptionalItem(snapshot);
     }
-    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnimplementedError`. */
+    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnsupportedError`. */
     getItemSequence(_c, _id) {
-        throw new UnimplementedError("FirestoreLiteProvider does not support realtime subscriptions");
+        throw new UnsupportedError("FirestoreLiteProvider does not support realtime subscriptions");
     }
     async addItem(c, data) {
         const reference = await addDoc(this._collection(c), data);
@@ -116,9 +116,9 @@ export class FirestoreLiteProvider extends DBProvider {
     async getQuery(c, q) {
         return _getItems(await getDocs(this._query(c, q)));
     }
-    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnimplementedError`. */
+    /** Not supported — the Firebase Lite SDK has no realtime listeners, so this throws `UnsupportedError`. */
     getQuerySequence(_c, _q) {
-        throw new UnimplementedError("FirestoreLiteProvider does not support realtime subscriptions");
+        throw new UnsupportedError("FirestoreLiteProvider does not support realtime subscriptions");
     }
     async setQuery(c, q, data) {
         const snapshot = await getDocs(this._query(c, q));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.271.3",
+	"version": "1.272.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/block/List.d.ts

@@ -1,4 +1,5 @@
 import type { ReactElement, ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
 import { type BlockVariants } from "../style/Block.js";
 import { type GapVariants } from "../style/Gap.js";
 /**
@@ -7,8 +8,8 @@ import { type GapVariants } from "../style/Gap.js";
  * @see https://shelving.cc/ui/ListProps
  */
 export interface ListProps extends GapVariants, BlockVariants {
-    children: ReactNode[];
-    ordered?: boolean;
+    readonly children: ImmutableArray<ReactNode>;
+    readonly ordered?: boolean | undefined;
 }
 /**
  * List block — wraps each child in an `<li>` and renders an `<ul>` or `<ol>`.

package/ui/block/List.tsx

@@ -1,4 +1,5 @@
 import type { ReactElement, ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { type GapVariants, getGapClass } from "../style/Gap.js";
 import { getClass, getModuleClass } from "../util/css.js";
@@ -13,8 +14,8 @@ const LIST_UNORDERED_CLASS = getModuleClass(LIST_CSS, "unordered");
  * @see https://shelving.cc/ui/ListProps
  */
 export interface ListProps extends GapVariants, BlockVariants {
-	children: ReactNode[];
-	ordered?: boolean;
+	readonly children: ImmutableArray<ReactNode>;
+	readonly ordered?: boolean | undefined;
 }
 
 /**

package/ui/input/Popover.d.ts

@@ -7,7 +7,7 @@ import type { Callback } from "../../util/function.js";
  *
  * @see https://shelving.cc/ui/PopoverChildren
  */
-export type PopoverChildren = [
+export type PopoverChildren = readonly [
     /**
      * First child of the <Popover> is element that activates the popover.
      * - Should be a `<Button>` or `<Input>` that activates or provides the children.

package/ui/input/Popover.tsx

@@ -15,7 +15,7 @@ import styles from "./Popover.module.css";
  *
  * @see https://shelving.cc/ui/PopoverChildren
  */
-export type PopoverChildren = [
+export type PopoverChildren = readonly [
 	/**
 	 * First child of the <Popover> is element that activates the popover.
 	 * - Should be a `<Button>` or `<Input>` that activates or provides the children.

package/ui/menu/Menu.d.ts

@@ -28,7 +28,7 @@ export interface MenuItemProps extends ClickableProps {
      * The first child becomes the link label (rendered inside the `<a>`).
      * - Any additional children form the submenu — only rendered when this item is "proud" (an ancestor of the current page). The caller is responsible for wrapping the submenu in a nested `<Menu>` if it wants the CSS `.menu .menu` descendant rules to apply.
      */
-    readonly children: ReactNode | [ReactNode, ...ReactNode[]];
+    readonly children: ReactNode | readonly [ReactNode, ...ReactNode[]];
 }
 /**
  * A `<li>` containing an `<a>` link, plus optional submenu content shown when this item is "proud".

package/ui/menu/Menu.tsx

@@ -52,7 +52,7 @@ export interface MenuItemProps extends ClickableProps {
 	 * The first child becomes the link label (rendered inside the `<a>`).
 	 * - Any additional children form the submenu — only rendered when this item is "proud" (an ancestor of the current page). The caller is responsible for wrapping the submenu in a nested `<Menu>` if it wants the CSS `.menu .menu` descendant rules to apply.
 	 */
-	readonly children: ReactNode | [ReactNode, ...ReactNode[]];
+	readonly children: ReactNode | readonly [ReactNode, ...ReactNode[]];
 }
 
 /**

package/error/UnimplementedError.js

@@ -1,14 +0,0 @@
-import { setBaseErrorOptions } from "./BaseError.js";
-/**
- * Error thrown when functionality is called but is not implemented by an interface.
- *
- * @see https://shelving.cc/error/UnimplementedError
- */
-export class UnimplementedError extends Error {
-    /** @param message Optional human-readable description of the missing implementation. */
-    constructor(message, options = {}) {
-        super(message, options);
-        setBaseErrorOptions(UnimplementedError, this, options);
-    }
-}
-UnimplementedError.prototype.name = "UnimplementedError";