shelving 1.132.0 → 1.133.0

package/api/Resource.js

@@ -1,6 +1,6 @@
 import { ValidationError } from "../error/ValidationError.js";
 import { Feedback } from "../feedback/Feedback.js";
-import { UNDEFINED_VALIDATOR } from "../util/validate.js";
+import { UNDEFINED } from "../util/validate.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions..
  *
@@ -15,7 +15,7 @@ export class Resource {
     payload;
     /** Result validator. */
     result;
-    constructor(name, payload = UNDEFINED_VALIDATOR, result = UNDEFINED_VALIDATOR) {
+    constructor(name, payload = UNDEFINED, result = UNDEFINED) {
         this.name = name;
         this.payload = payload;
         this.result = result;

package/db/ValidationProvider.d.ts

@@ -1,4 +1,4 @@
-import type { DataSchema, DatabaseSchemas } from "../schema/DataSchema.js";
+import type { DataSchema, DataSchemas } from "../schema/DataSchema.js";
 import type { DataKey, Database } from "../util/data.js";
 import type { ItemQuery, Items, OptionalItem } from "../util/item.js";
 import type { Sourceable } from "../util/source.js";
@@ -7,8 +7,8 @@ import type { AsyncProvider, Provider } from "./Provider.js";
 import { AsyncThroughProvider, ThroughProvider } from "./ThroughProvider.js";
 /** Validate a synchronous source provider (source can have any type because validation guarantees the type). */
 export declare class ValidationProvider<T extends Database> extends ThroughProvider<T> implements Provider<T>, Sourceable<Provider<T>> {
-    readonly schemas: DatabaseSchemas<T>;
-    constructor(schemas: DatabaseSchemas<T>, source: Provider<T>);
+    readonly schemas: DataSchemas<T>;
+    constructor(schemas: DataSchemas<T>, source: Provider<T>);
     /** Get a named schema. */
     getSchema<K extends DataKey<T>>(collection: K): DataSchema<T[K]>;
     getItem<K extends DataKey<T>>(collection: K, id: string): OptionalItem<T[K]>;
@@ -26,8 +26,9 @@ export declare class ValidationProvider<T extends Database> extends ThroughProvi
 }
 /** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
 export declare class AsyncValidationProvider<T extends Database> extends AsyncThroughProvider<T> implements AsyncProvider<T>, Sourceable<AsyncProvider<T>> {
-    readonly schemas: DatabaseSchemas<T>;
-    constructor(schemas: DatabaseSchemas<T>, source: AsyncProvider<T>);
+    readonly schemas: DataSchemas<T>;
+    constructor(schemas: DataSchemas<T>, source: AsyncProvider<T>);
+    /** Get a named data schema for this database. */
     getSchema<K extends DataKey<T>>(collection: K): DataSchema<T[K]>;
     getItem<K extends DataKey<T>>(collection: K, id: string): Promise<OptionalItem<T[K]>>;
     getItemSequence<K extends DataKey<T>>(collection: K, id: string): AsyncIterable<OptionalItem<T[K]>>;

package/db/ValidationProvider.js

@@ -1,13 +1,9 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { ValidationError as ConflictError } from "../error/ValidationError.js";
 import { Feedback } from "../feedback/Feedback.js";
+import { KEY } from "../schema/KeySchema.js";
 import { updateData } from "../util/update.js";
-import { validateWithContext } from "../util/validate.js";
+import { validateData } from "../util/validate.js";
 import { AsyncThroughProvider, ThroughProvider } from "./ThroughProvider.js";
-// Constants.
-const VALIDATION_CONTEXT_GET = { action: "get", id: true };
-const VALIDATION_CONTEXT_ADD = { action: "add" };
-const VALIDATION_CONTEXT_SET = { action: "set" };
-const VALIDATION_CONTEXT_UPDATE = { action: "update", partial: true };
 /** Validate a synchronous source provider (source can have any type because validation guarantees the type). */
 export class ValidationProvider extends ThroughProvider {
     schemas;
@@ -28,13 +24,13 @@ export class ValidationProvider extends ThroughProvider {
             yield _validateItem(collection, unsafeItem, schema);
     }
     addItem(collection, data) {
-        return super.addItem(collection, validateWithContext(data, this.getSchema(collection), VALIDATION_CONTEXT_ADD));
+        return super.addItem(collection, validateData(data, this.getSchema(collection).props));
     }
     setItem(collection, id, data) {
-        super.setItem(collection, id, validateWithContext(data, this.getSchema(collection), VALIDATION_CONTEXT_SET));
+        super.setItem(collection, id, validateData(data, this.getSchema(collection).props));
     }
     updateItem(collection, id, updates) {
-        validateWithContext(updateData({}, updates), this.getSchema(collection), VALIDATION_CONTEXT_UPDATE);
+        validateData(updateData({}, updates), this.getSchema(collection).props, true);
         super.updateItem(collection, id, updates);
     }
     deleteItem(collection, id) {
@@ -50,7 +46,7 @@ export class ValidationProvider extends ThroughProvider {
         super.setQuery(collection, query, this.getSchema(collection).validate(data));
     }
     updateQuery(collection, query, updates) {
-        validateWithContext(updateData({}, updates), this.getSchema(collection), VALIDATION_CONTEXT_UPDATE);
+        validateData(updateData({}, updates), this.getSchema(collection).props, true);
         super.updateQuery(collection, query, updates);
     }
     deleteQuery(collection, query) {
@@ -69,6 +65,7 @@ export class AsyncValidationProvider extends AsyncThroughProvider {
         super(source);
         this.schemas = schemas;
     }
+    /** Get a named data schema for this database. */
     getSchema(collection) {
         return this.schemas[collection];
     }
@@ -81,13 +78,13 @@ export class AsyncValidationProvider extends AsyncThroughProvider {
             yield _validateItem(collection, unsafeItem, schema);
     }
     addItem(collection, data) {
-        return super.addItem(collection, validateWithContext(data, this.getSchema(collection), VALIDATION_CONTEXT_ADD));
+        return super.addItem(collection, validateData(data, this.getSchema(collection).props));
     }
     setItem(collection, id, data) {
-        return super.setItem(collection, id, validateWithContext(data, this.getSchema(collection), VALIDATION_CONTEXT_SET));
+        return super.setItem(collection, id, validateData(data, this.getSchema(collection).props));
     }
     updateItem(collection, id, updates) {
-        validateWithContext(updateData({}, updates), this.getSchema(collection), VALIDATION_CONTEXT_UPDATE);
+        validateData(updateData({}, updates), this.getSchema(collection).props, true);
         return super.updateItem(collection, id, updates);
     }
     deleteItem(collection, id) {
@@ -105,46 +102,49 @@ export class AsyncValidationProvider extends AsyncThroughProvider {
             yield _validateItems(collection, unsafeItems, schema);
     }
     setQuery(collection, query, data) {
-        return super.setQuery(collection, query, validateWithContext(data, this.getSchema(collection), VALIDATION_CONTEXT_SET));
+        return super.setQuery(collection, query, validateData(data, this.getSchema(collection).props));
     }
     updateQuery(collection, query, updates) {
-        validateWithContext(updateData({}, updates), this.getSchema(collection), VALIDATION_CONTEXT_UPDATE);
+        validateData(updateData({}, updates), this.getSchema(collection).props, true);
         return super.updateQuery(collection, query, updates);
     }
     deleteQuery(collection, query) {
         return super.deleteQuery(collection, query);
     }
 }
-function _validateItem(collection, unsafeEntity, schema) {
-    if (!unsafeEntity)
+function _validateItem(collection, unsafeItem, schema) {
+    if (!unsafeItem)
         return undefined;
     try {
-        return validateWithContext(unsafeEntity, schema, VALIDATION_CONTEXT_GET);
+        return validateData(unsafeItem, { id: KEY, ...schema.props });
     }
     catch (thrown) {
         if (!(thrown instanceof Feedback))
             throw thrown;
-        throw new ValidationError(`Invalid data for "${collection}"`, thrown.message);
+        throw new ConflictError(`Invalid data for "${collection}"`, thrown.message);
     }
 }
-/** Validate a set of entities for this query reference. */
+/**
+ * Validate a set of entities for this query reference.
+ * @throws `ConflictError` if one or more items did not validate (conflict because the program is not in an expected state).
+ */
 function _validateItems(collection, unsafeEntities, schema) {
-    return Array.from(_yieldValidItems(collection, unsafeEntities, schema));
+    return Array.from(_yieldValidItems(collection, unsafeEntities, { id: KEY, ...schema.props }));
 }
-function* _yieldValidItems(collection, unsafeEntities, schema) {
+function* _yieldValidItems(collection, unsafeEntities, validators) {
     let invalid = false;
     const messages = {};
-    for (const unsafeEntity of unsafeEntities) {
+    for (const unsafeItem of unsafeEntities) {
         try {
-            yield validateWithContext(unsafeEntity, schema, VALIDATION_CONTEXT_GET);
+            yield validateData(unsafeItem, validators);
         }
         catch (thrown) {
             if (!(thrown instanceof Feedback))
                 throw thrown;
             invalid = true;
-            messages[unsafeEntity.id] = thrown.message;
+            messages[unsafeItem.id] = thrown.message;
         }
     }
     if (invalid)
-        throw new ValidationError(`Invalid data for "${collection}"`, messages);
+        throw new ConflictError(`Invalid data for "${collection}"`, messages);
 }

package/error/UnauthorizedError.d.ts

@@ -1,6 +1,6 @@
 import { EnhancedError } from "./EnhancedError.js";
 /** Thrown if an operation failed because the user is logged in but does not have sufficient privileges to access something. */
 export declare class UnauthorizedError extends EnhancedError {
-    readonly code = 403;
+    readonly code = 401;
     constructor(message?: string, context?: unknown);
 }

package/error/UnauthorizedError.js

@@ -1,7 +1,7 @@
 import { EnhancedError } from "./EnhancedError.js";
 /** Thrown if an operation failed because the user is logged in but does not have sufficient privileges to access something. */
 export class UnauthorizedError extends EnhancedError {
-    code = 403;
+    code = 401;
     constructor(message = "Unauthorized", context) {
         super(message, context);
     }

package/package.json

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

package/schema/DataSchema.d.ts

@@ -16,7 +16,7 @@ export declare class DataSchema<T extends Data> extends Schema<T> {
     validate(unsafeValue?: unknown): T;
 }
 /** Set of named data schemas. */
-export type DatabaseSchemas<T extends Database> = {
+export type DataSchemas<T extends Database> = {
     [K in keyof T]: DataSchema<T[K]>;
 };
 /** Valid data object with specifed properties. */

package/schema/ItemSchema.d.ts

@@ -0,0 +1,33 @@
+import type { Data, Database } from "../util/data.js";
+import type { Item } from "../util/item.js";
+import type { Validators } from "../util/validate.js";
+import { DataSchema } from "./DataSchema.js";
+import type { KeySchema } from "./KeySchema.js";
+import { type OptionalSchema } from "./OptionalSchema.js";
+import type { SchemaOptions } from "./Schema.js";
+/** Allowed options for `ItemSchema` */
+export interface ItemSchemaOptions<T extends Data> extends SchemaOptions {
+    readonly id?: KeySchema | undefined;
+    readonly props: Validators<T>;
+    readonly value?: Partial<Item<T>> | undefined;
+}
+/** Validate an item object. */
+export declare class ItemSchema<T extends Data> extends DataSchema<Item<T>> {
+    constructor({ id, props, ...options }: ItemSchemaOptions<T>);
+}
+/** Set of named item schemas. */
+export type ItemSchemas<T extends Database> = {
+    [K in keyof T]: DataSchema<Item<T[K]>>;
+};
+/**
+ * Valid item object with specifed properties.
+ * - An `Item` is a `Data` object with a string `.id` prop.
+ * - Optional validator for `.id` must be a `KeySchema` and defaults to `KEY`.
+ */
+export declare const ITEM: <T extends Data>(props: Validators<T> | DataSchema<T>, id?: KeySchema) => ItemSchema<Item<T>>;
+/**
+ * Valid item object or `null`.
+ * - An `Item` is a `Data` object with a string `.id` prop.
+ * - Optional validator for `.id` must be a `KeySchema` and defaults to `KEY`.
+ */
+export declare const OPTIONAL_ITEM: <T extends Data>(props: Validators<T> | DataSchema<T>, id?: KeySchema) => OptionalSchema<Item<T>>;

package/schema/ItemSchema.js

@@ -0,0 +1,21 @@
+import { DataSchema } from "./DataSchema.js";
+import { KEY } from "./KeySchema.js";
+import { OPTIONAL } from "./OptionalSchema.js";
+/** Validate an item object. */
+export class ItemSchema extends DataSchema {
+    constructor({ id = KEY, props, ...options }) {
+        super({ props: { id, ...props }, ...options });
+    }
+}
+/**
+ * Valid item object with specifed properties.
+ * - An `Item` is a `Data` object with a string `.id` prop.
+ * - Optional validator for `.id` must be a `KeySchema` and defaults to `KEY`.
+ */
+export const ITEM = (props, id) => props instanceof DataSchema ? new ItemSchema({ id, ...props }) : new ItemSchema({ props, id });
+/**
+ * Valid item object or `null`.
+ * - An `Item` is a `Data` object with a string `.id` prop.
+ * - Optional validator for `.id` must be a `KeySchema` and defaults to `KEY`.
+ */
+export const OPTIONAL_ITEM = (props, id) => OPTIONAL(ITEM(props, id));

package/schema/index.d.ts

@@ -9,6 +9,7 @@ export * from "./DictionarySchema.js";
 export * from "./EmailSchema.js";
 export * from "./EntitySchema.js";
 export * from "./FileSchema.js";
+export * from "./ItemSchema.js";
 export * from "./KeySchema.js";
 export * from "./LinkSchema.js";
 export * from "./NumberSchema.js";

package/schema/index.js

@@ -9,6 +9,7 @@ export * from "./DictionarySchema.js";
 export * from "./EmailSchema.js";
 export * from "./EntitySchema.js";
 export * from "./FileSchema.js";
+export * from "./ItemSchema.js";
 export * from "./KeySchema.js";
 export * from "./LinkSchema.js";
 export * from "./NumberSchema.js";

package/util/validate.d.ts

@@ -1,7 +1,7 @@
 import type { ImmutableArray, PossibleArray } from "./array.js";
 import type { Data } from "./data.js";
 import type { ImmutableDictionary, PossibleDictionary } from "./dictionary.js";
-import type { Item } from "./item.js";
+import type { DeepPartial } from "./object.js";
 /** Object that can validate an unknown value with its `validate()` method. */
 export interface Validator<T> {
     /**
@@ -58,19 +58,13 @@ export declare function validateDictionary<T>(unsafeDictionary: PossibleDictiona
  * - Defined props in the object will be validated against the corresponding validator.
  * - `undefined` props in the object will be set to the default value of that prop.
  *
+ * @param partial Whether we're validating a partial match, or not.
  * @return Valid object.
  * @throw Feedback if one or more props did not validate.
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
-export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>): T;
-/** Get the current validation context. */
-export declare function getValidationContext(): Data;
-/** Validate a unknown value with a validator, and supply a context that can be read during the validation process. */
-export declare function validateWithContext<T extends Data>(unsafeValue: Item<Data>, validator: Validator<T>, context: Data & {
-    readonly id: true;
-}): Item<T>;
-export declare function validateWithContext<T extends Data>(unsafeValue: unknown, validator: Validator<T>, context: Data & {
-    readonly partial: true;
-}): Partial<T>;
-export declare function validateWithContext<T>(unsafeValue: unknown, validator: Validator<T>, context: Data): T;
-export declare const UNDEFINED_VALIDATOR: Validator<undefined>;
+export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>, partial: true): DeepPartial<T>;
+export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>, partial?: false): T;
+export declare const UNDEFINED: Validator<undefined>;
+export declare const NULL: Validator<null>;
+export declare const UNKNOWN: Validator<unknown>;

package/util/validate.js

@@ -1,10 +1,12 @@
 import { ValidationError } from "../error/ValidationError.js";
 import { Feedback } from "../feedback/Feedback.js";
 import { ValueFeedbacks } from "../feedback/Feedbacks.js";
-import { getLastItem, isArray } from "./array.js";
+import { isArray } from "./array.js";
 import { getDataProps } from "./data.js";
 import { getDictionaryItems } from "./dictionary.js";
+import { PASSTHROUGH } from "./function.js";
 import { isIterable } from "./iterate.js";
+import { getNull } from "./null.js";
 import { getUndefined } from "./undefined.js";
 /** Get value that validates against a given `Validator`, or throw `ValidationError` */
 export function getValid(unsafeValue, validator) {
@@ -108,53 +110,43 @@ export function validateDictionary(unsafeDictionary, validator) {
         throw new ValueFeedbacks(messages, unsafeDictionary);
     return changed || isIterable(unsafeDictionary) ? safeDictionary : unsafeDictionary;
 }
-/**
- * Validate a data object with a set of validators.
- * - Defined props in the object will be validated against the corresponding validator.
- * - `undefined` props in the object will be set to the default value of that prop.
- *
- * @return Valid object.
- * @throw Feedback if one or more props did not validate.
- * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
- */
-export function validateData(unsafeData, validators) {
-    const { partial = false, id = false } = getValidationContext();
+/** Keep track of whether we're doing a deep-partial match or not. */
+let isDeeplyPartial = false;
+export function validateData(unsafeData, validators, partial = isDeeplyPartial) {
     let valid = true;
     let changed = true;
-    const safeData = id && typeof unsafeData.id === "string" ? { id: unsafeData.id } : {};
+    const safeData = {};
     const messages = {};
-    for (const [key, validator] of getDataProps(validators)) {
-        const unsafeValue = unsafeData[key];
-        if (unsafeValue === undefined && partial)
-            continue; // Silently skip `undefined` props if in partial mode.
-        try {
-            const safeValue = validator.validate(unsafeValue);
-            safeData[key] = safeValue;
-            if (!changed && safeValue !== unsafeValue)
-                changed = true;
-        }
-        catch (thrown) {
-            if (!(thrown instanceof Feedback))
-                throw thrown;
-            messages[key] = thrown.message;
-            valid = false;
+    try {
+        isDeeplyPartial = partial;
+        for (const [key, validator] of getDataProps(validators)) {
+            const unsafeValue = unsafeData[key];
+            if (unsafeValue === undefined && partial)
+                continue; // Silently skip `undefined` props if in partial mode.
+            try {
+                const safeValue = validator.validate(unsafeValue);
+                safeData[key] = safeValue;
+                if (!changed && safeValue !== unsafeValue)
+                    changed = true;
+            }
+            catch (thrown) {
+                if (!(thrown instanceof Feedback))
+                    throw thrown;
+                messages[key] = thrown.message;
+                valid = false;
+            }
         }
+        if (!valid)
+            throw new ValueFeedbacks(messages, unsafeData);
+        return changed ? safeData : unsafeData;
+    }
+    finally {
+        isDeeplyPartial = false;
     }
-    if (!valid)
-        throw new ValueFeedbacks(messages, unsafeData);
-    return changed ? safeData : unsafeData;
-}
-/** Store a list of current contexts. */
-const CONTEXTS = [{}];
-/** Get the current validation context. */
-export function getValidationContext() {
-    return getLastItem(CONTEXTS);
-}
-export function validateWithContext(unsafeValue, validator, context) {
-    CONTEXTS.push(context);
-    const validValue = validator.validate(unsafeValue);
-    CONTEXTS.pop();
-    return validValue;
 }
-// Undefined validator always returns undefined.
-export const UNDEFINED_VALIDATOR = { validate: getUndefined };
+// Undefined validator always returns `undefined`
+export const UNDEFINED = { validate: getUndefined };
+// Null validator always returns `null`
+export const NULL = { validate: getNull };
+// Unknown validator always passes through its input value as `unknown`
+export const UNKNOWN = { validate: PASSTHROUGH };