shelving 1.82.0 → 1.83.0

package/schema/Schema.d.ts

@@ -1,4 +1,13 @@
 import type { Validatable } from "../util/validate.js";
+/** Options allowed by a `Schema` instance. */
+export declare type SchemaOptions = {
+    /** Title of the schema, e.g. for using as the title of a corresponding field. */
+    readonly title?: string;
+    /** Description of the schema, e.g. for using as a description in a corresponding field. */
+    readonly description?: string;
+    /** Placeholder of the schema, e.g. for using as a placeholder in a corresponding field. */
+    readonly placeholder?: string;
+};
 /**
  * Schema is an object instance with a `validate()` method.
  * - Type `T` represents the type of value `validate()` returns.
@@ -13,14 +22,7 @@ export declare abstract class Schema<T extends unknown = unknown> implements Val
     readonly placeholder: string;
     /** Default value. */
     readonly value: unknown;
-    constructor({ title, description, placeholder, }: {
-        /** Title of the schema, e.g. for using as the title of a corresponding field. */
-        readonly title?: string;
-        /** Description of the schema, e.g. for using as a description in a corresponding field. */
-        readonly description?: string;
-        /** Placeholder of the schema, e.g. for using as a placeholder in a corresponding field. */
-        readonly placeholder?: string;
-    });
+    constructor({ title, description, placeholder }: SchemaOptions);
     /** Every schema must implement a `validate()` method. */
     abstract validate(unsafeValue: unknown): T;
 }

package/schema/Schema.js

@@ -4,7 +4,7 @@
  * - `validate()` returns `Invalid` if value was not valid.
  */
 export class Schema {
-    constructor({ title = "", description = "", placeholder = "", }) {
+    constructor({ title = "", description = "", placeholder = "" }) {
         this.title = title;
         this.description = description;
         this.placeholder = placeholder;

package/schema/StringSchema.d.ts

@@ -1,8 +1,18 @@
-import { Schema } from "./Schema.js";
+import { Schema, SchemaOptions } from "./Schema.js";
 /** `type=""` prop for HTML `<input />` tags that are relevant for strings. */
 export declare type HtmlInputType = "text" | "password" | "color" | "date" | "email" | "number" | "tel" | "search" | "url";
 /** Function that sanitizes a string. */
 export declare type Sanitizer = (str: string) => string;
+/** Options for `StringSchema` */
+export declare type StringSchemaOptions = SchemaOptions & {
+    readonly value?: string;
+    readonly type?: HtmlInputType;
+    readonly min?: number;
+    readonly max?: number | null;
+    readonly match?: RegExp | null;
+    readonly sanitizer?: Sanitizer | null;
+    readonly multiline?: boolean;
+};
 /**
  * Schema that defines a valid string.
  *
@@ -31,15 +41,7 @@ export declare class StringSchema extends Schema<string> {
     readonly match: RegExp | null;
     readonly sanitizer: Sanitizer | null;
     readonly multiline: boolean;
-    constructor({ value, type, min, max, match, sanitizer, multiline, ...rest }: ConstructorParameters<typeof Schema>[0] & {
-        readonly value?: string;
-        readonly type?: HtmlInputType;
-        readonly min?: number;
-        readonly max?: number | null;
-        readonly match?: RegExp | null;
-        readonly sanitizer?: Sanitizer | null;
-        readonly multiline?: boolean;
-    });
+    constructor({ value, type, min, max, match, sanitizer, multiline, ...rest }: StringSchemaOptions);
     validate(unsafeValue?: unknown): string;
     /**
      * Clean a string by removing characters that aren't digits.

package/schema/index.d.ts

@@ -5,11 +5,11 @@ export * from "./BooleanSchema.js";
 export * from "./ColorSchema.js";
 export * from "./DataSchema.js";
 export * from "./DateSchema.js";
+export * from "./DictionarySchema.js";
 export * from "./EmailSchema.js";
 export * from "./KeySchema.js";
 export * from "./LinkSchema.js";
 export * from "./NumberSchema.js";
-export * from "./ObjectSchema.js";
 export * from "./OptionalSchema.js";
 export * from "./PhoneSchema.js";
 export * from "./RequiredSchema.js";

package/schema/index.js

@@ -5,11 +5,11 @@ export * from "./BooleanSchema.js";
 export * from "./ColorSchema.js";
 export * from "./DataSchema.js";
 export * from "./DateSchema.js";
+export * from "./DictionarySchema.js";
 export * from "./EmailSchema.js";
 export * from "./KeySchema.js";
 export * from "./LinkSchema.js";
 export * from "./NumberSchema.js";
-export * from "./ObjectSchema.js";
 export * from "./OptionalSchema.js";
 export * from "./PhoneSchema.js";
 export * from "./RequiredSchema.js";

package/state/ArrayState.js

@@ -1,4 +1,4 @@
-import { toggleItems, withItems, withoutItems } from "../util/array.js";
+import { toggleArrayItems, withArrayItems, withoutArrayItems } from "../util/array.js";
 import { State } from "./State.js";
 /** State that stores an array and has additional methods to help with that. */
 export class ArrayState extends State {
@@ -11,15 +11,15 @@ export class ArrayState extends State {
     }
     /** Add items to this array. */
     add(...items) {
-        this.set(withItems(this.value, ...items));
+        this.set(withArrayItems(this.value, ...items));
     }
     /** Remove items from this array. */
     delete(...items) {
-        this.set(withoutItems(this.value, ...items));
+        this.set(withoutArrayItems(this.value, ...items));
     }
     /** Toggle items in this array. */
     toggle(...items) {
-        this.set(toggleItems(this.value, ...items));
+        this.set(toggleArrayItems(this.value, ...items));
     }
     /** Iterate over the items. */
     [Symbol.iterator]() {

package/state/DataState.js

@@ -1,5 +1,5 @@
 import { getData } from "../util/data.js";
-import { transformData } from "../util/transform.js";
+import { transformObject } from "../util/transform.js";
 import { State } from "./State.js";
 /** State that stores a data object and has additional methods to help with that. */
 export class DataState extends State {
@@ -9,7 +9,7 @@ export class DataState extends State {
     }
     /** Update several props in this data. */
     update(updates) {
-        this.set(transformData(this.data, updates));
+        this.set(transformObject(this.data, updates));
     }
 }
 /** State that stores an optional data object and has additional methods to help with that. */
@@ -24,7 +24,7 @@ export class OptionalDataState extends State {
     }
     /** Update several props in this data. */
     update(updates) {
-        this.set(transformData(this.data, updates));
+        this.set(transformObject(this.data, updates));
     }
     /** Set the data to `null`. */
     unset() {

package/state/DictionaryState.d.ts

@@ -0,0 +1,15 @@
+import { DictionaryItem, ImmutableDictionary } from "../util/dictionary.js";
+import { Transformers } from "../util/transform.js";
+import { State } from "./State.js";
+/** State that stores a dictionary object and has additional methods to help with that. */
+export declare class DictionaryState<T> extends State<ImmutableDictionary<T>> implements Iterable<DictionaryItem<T>> {
+    constructor(initial?: ImmutableDictionary<T>);
+    /** Get the length of the current value of this state. */
+    get count(): number;
+    /** Set a named entry in this object with a different value. */
+    update(updates: Transformers<ImmutableDictionary<T>>): void;
+    /** Remove a named entry from this object. */
+    delete(...keys: string[]): void;
+    /** Iterate over the entries of the object. */
+    [Symbol.iterator](): Iterator<DictionaryItem<T>>;
+}

package/state/{ObjectState.js → DictionaryState.js}

@@ -1,8 +1,8 @@
-import { withoutProps } from "../util/object.js";
-import { transformData } from "../util/transform.js";
+import { withoutDictionaryItems } from "../util/dictionary.js";
+import { transformDictionary } from "../util/transform.js";
 import { State } from "./State.js";
-/** State that stores a map-like object and has additional methods to help with that. */
-export class ObjectState extends State {
+/** State that stores a dictionary object and has additional methods to help with that. */
+export class DictionaryState extends State {
     constructor(initial = {}) {
         super(initial);
     }
@@ -12,11 +12,11 @@ export class ObjectState extends State {
     }
     /** Set a named entry in this object with a different value. */
     update(updates) {
-        this.set(transformData(this.value, updates));
+        this.set(transformDictionary(this.value, updates));
     }
     /** Remove a named entry from this object. */
     delete(...keys) {
-        this.set(withoutProps(this.value, ...keys));
+        this.set(withoutDictionaryItems(this.value, ...keys));
     }
     /** Iterate over the entries of the object. */
     [Symbol.iterator]() {

package/state/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./State.js";
-export * from "./BooleanState.js";
 export * from "./ArrayState.js";
-export * from "./ObjectState.js";
+export * from "./BooleanState.js";
 export * from "./DataState.js";
+export * from "./DictionaryState.js";

package/state/index.js

@@ -1,5 +1,5 @@
 export * from "./State.js";
-export * from "./BooleanState.js";
 export * from "./ArrayState.js";
-export * from "./ObjectState.js";
+export * from "./BooleanState.js";
 export * from "./DataState.js";
+export * from "./DictionaryState.js";

package/test/basics.js

@@ -6,7 +6,7 @@ import { STRING } from "../schema/StringSchema.js";
 export const BASIC_SCHEMA = DATA({
     str: STRING,
     num: NUMBER,
-    group: ALLOW_STRING(["a", "b", "c"]),
+    group: ALLOW_STRING({ a: "A", b: "B", c: "C" }),
     tags: ARRAY(STRING),
 });
 export const basic1 = { id: "basic1", str: "aaa", num: 100, group: "a", tags: ["odd", "prime"] };

package/update/ArrayUpdate.js

@@ -1,5 +1,5 @@
 import { ArraySchema } from "../schema/ArraySchema.js";
-import { withItems, withoutItems } from "../util/array.js";
+import { withArrayItems, withoutArrayItems } from "../util/array.js";
 import { validateArray } from "../util/validate.js";
 import { Update } from "./Update.js";
 /** Update that can be applied to an array to add/remove items. */
@@ -18,7 +18,7 @@ export class ArrayUpdate extends Update {
         return new ArrayUpdate([], deletes);
     }
     transform(arr = []) {
-        return withoutItems(withItems(arr, ...this.adds), ...this.deletes);
+        return withoutArrayItems(withArrayItems(arr, ...this.adds), ...this.deletes);
     }
     validate(validator) {
         if (!(validator instanceof ArraySchema))

package/update/DataUpdate.d.ts

@@ -1,14 +1,13 @@
-import { Data, Key, Prop } from "../util/data.js";
+import { Data, DataKey, DataProp } from "../util/data.js";
 import { Nullish } from "../util/null.js";
 import { Transformable } from "../util/transform.js";
 import { Validator, Validators } from "../util/validate.js";
 import { Update } from "./Update.js";
 /**
- * Set of named transforms for the props of a data object.
- * - Named transforms probably correspond to the properties of an object.
+ * Set of named updates for the props of a data object.
+ * - Similar to `Transformers` but only allows `Update` instances.
  * - If a prop contains a new value, the prop is set to that new value.
- * - If a prop contains a transform, the existing value is transformed.
- * - This is a subset of `Dispatchers`
+ * - If a prop contains an `Update` instance, the existing value is updated.
  */
 export declare type Updates<T extends Data = Data> = {
     readonly [K in keyof T]?: T[K] | Update<T[K]>;
@@ -17,18 +16,20 @@ export declare type Updates<T extends Data = Data> = {
  * Validate a set of updates against a set of validators.
  */
 export declare function validateUpdates<T extends Data>(unsafeUpdates: Updates<T>, validators: Validators<T>): Updates<T>;
+/** Update data using a set of updates. */
+export declare const updateData: <T extends Data>(data: T, updates: Updates<T>) => T;
 /**
  * Update that can be applied to a data object to update its props.
  */
-export declare class DataUpdate<T extends Data = Data> extends Update<T> implements Iterable<Prop<Updates<T>>>, Transformable<T, T> {
+export declare class DataUpdate<T extends Data = Data> extends Update<T> implements Iterable<DataProp<Updates<T>>>, Transformable<T, T> {
     /** Return a data update with a specific prop marked for update. */
-    static with<X extends Data, K extends Key<X>>(key: Nullish<K>, value: X[K] | Update<X[K]>): DataUpdate<X>;
+    static with<X extends Data, K extends DataKey<X>>(key: Nullish<K>, value: X[K] | Update<X[K]>): DataUpdate<X>;
     readonly updates: Updates<T>;
     constructor(props: Updates<T>);
     transform(data: T): T;
     validate(validator: Validator<T>): this;
     /** Return a data update with a specific prop marked for update. */
-    with<K extends Key<T>>(key: Nullish<K>, value: T[K] | Update<T[K]>): this;
+    with<K extends DataKey<T>>(key: Nullish<K>, value: T[K] | Update<T[K]>): this;
     /** Iterate over the transforms in this object. */
-    [Symbol.iterator](): Iterator<Prop<Updates<T>>, void>;
+    [Symbol.iterator](): Iterator<DataProp<Updates<T>>, void>;
 }

package/update/DataUpdate.js

@@ -1,9 +1,9 @@
 import { isFeedback } from "../feedback/Feedback.js";
 import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
 import { DataSchema } from "../schema/DataSchema.js";
-import { getProps } from "../util/object.js";
+import { getDataProps } from "../util/data.js";
 import { isNullish } from "../util/null.js";
-import { transformData } from "../util/transform.js";
+import { transformObject } from "../util/transform.js";
 import { validate } from "../util/validate.js";
 import { Update } from "./Update.js";
 /**
@@ -14,7 +14,7 @@ export function validateUpdates(unsafeUpdates, validators) {
 }
 function* _validateUpdates(unsafeUpdates, validators) {
     const feedbacks = new Map();
-    for (const [key, validator] of getProps(validators)) {
+    for (const [key, validator] of getDataProps(validators)) {
         const unsafeUpdate = unsafeUpdates[key];
         if (unsafeUpdate !== undefined) {
             try {
@@ -30,6 +30,8 @@ function* _validateUpdates(unsafeUpdates, validators) {
     if (feedbacks.size)
         throw new InvalidFeedback("Invalid updates", feedbacks);
 }
+/** Update data using a set of updates. */
+export const updateData = transformObject;
 /**
  * Update that can be applied to a data object to update its props.
  */
@@ -43,7 +45,7 @@ export class DataUpdate extends Update {
         return new DataUpdate(!isNullish(key) ? { [key]: value } : {});
     }
     transform(data) {
-        return transformData(data, this.updates);
+        return updateData(data, this.updates);
     }
     validate(validator) {
         if (!(validator instanceof DataSchema))

package/update/DictionaryUpdate.d.ts

@@ -0,0 +1,29 @@
+import type { Entry } from "../util/entry.js";
+import { Nullish } from "../util/null.js";
+import { ImmutableDictionary } from "../util/dictionary.js";
+import { Validator } from "../util/validate.js";
+import { Update } from "./Update.js";
+import { Delete } from "./Delete.js";
+/** Set of named transforms for the entries of a dictionary object. */
+export declare type DictionaryUpdates<T> = ImmutableDictionary<T | Update<T> | Delete>;
+/** Update that can be applied to a dictionary object to add/remove/update its entries. */
+export declare class DictionaryUpdate<T> extends Update<ImmutableDictionary<T>> implements Iterable<Entry<string, T | Update<T> | Delete>> {
+    /** Return a dictionary update with a specific entry marked for update. */
+    static with<X>(key: Nullish<string>, value: X | Update<X> | Delete): DictionaryUpdate<X>;
+    /** Return a dictionary update with a specific entry marked for deletion. */
+    static without<X>(key: Nullish<string>): DictionaryUpdate<X>;
+    readonly updates: DictionaryUpdates<T>;
+    constructor(updates?: DictionaryUpdates<T>);
+    transform(obj?: ImmutableDictionary<T>): ImmutableDictionary<T>;
+    validate(validator: Validator<ImmutableDictionary<T>>): this;
+    /** Return a dictionary update with a specific entry marked for update. */
+    with(key: Nullish<string>, value: T | Update<T>): this;
+    /** Return a dictionary update with a specific entry marked for deletion. */
+    without(key: Nullish<string>): this;
+    /**
+     * Iterate over the changes in this object.
+     * - Updates are yielded first, then deletes.
+     * - Entries whose value is `undefined` indicate deletion.
+     */
+    [Symbol.iterator](): Iterator<Entry<string, T | Update<T> | Delete>, void>;
+}

package/update/{ObjectUpdate.js → DictionaryUpdate.js}

@@ -1,38 +1,38 @@
 import { isNullish } from "../util/null.js";
 import { transform } from "../util/transform.js";
-import { ObjectSchema } from "../schema/ObjectSchema.js";
+import { DictionarySchema } from "../schema/DictionarySchema.js";
 import { validate } from "../util/validate.js";
 import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
 import { isFeedback } from "../feedback/Feedback.js";
 import { Update } from "./Update.js";
 import { Delete, DELETE } from "./Delete.js";
-/** Update that can be applied to a map-like object to add/remove/update its entries. */
-export class ObjectUpdate extends Update {
+/** Update that can be applied to a dictionary object to add/remove/update its entries. */
+export class DictionaryUpdate extends Update {
     constructor(updates = {}) {
         super();
         this.updates = updates;
     }
-    /** Return an object update with a specific entry marked for update. */
+    /** Return a dictionary update with a specific entry marked for update. */
     static with(key, value) {
-        return new ObjectUpdate(isNullish(key) ? {} : { [key]: value });
+        return new DictionaryUpdate(isNullish(key) ? {} : { [key]: value });
     }
-    /** Return an object update with a specific entry marked for deletion. */
+    /** Return a dictionary update with a specific entry marked for deletion. */
     static without(key) {
-        return new ObjectUpdate(isNullish(key) ? {} : { [key]: DELETE });
+        return new DictionaryUpdate(isNullish(key) ? {} : { [key]: DELETE });
     }
     transform(obj = {}) {
-        return Object.fromEntries(_transformEntries(obj, this.updates));
+        return Object.fromEntries(_transformDictionaryEntries(obj, this.updates));
     }
     validate(validator) {
-        if (!(validator instanceof ObjectSchema))
+        if (!(validator instanceof DictionarySchema))
             return super.validate(validator);
         return {
             __proto__: Object.getPrototypeOf(this),
             ...this,
-            updates: Object.fromEntries(_validateUpdates(this.updates, validator.items)),
+            updates: Object.fromEntries(_validateDictionaryUpdates(this.updates, validator.items)),
         };
     }
-    /** Return an object update with a specific entry marked for update. */
+    /** Return a dictionary update with a specific entry marked for update. */
     with(key, value) {
         if (isNullish(key))
             return this;
@@ -42,7 +42,7 @@ export class ObjectUpdate extends Update {
             updates: { ...this.updates, [key]: value },
         };
     }
-    /** Return an object update with a specific entry marked for deletion. */
+    /** Return a dictionary update with a specific entry marked for deletion. */
     without(key) {
         if (isNullish(key))
             return this;
@@ -62,14 +62,14 @@ export class ObjectUpdate extends Update {
             yield entry;
     }
 }
-function* _transformEntries(obj, updates) {
+function* _transformDictionaryEntries(obj, updates) {
     for (const [k, v] of Object.entries({ ...obj, ...updates })) {
         if (v instanceof Delete)
             continue;
         yield [k, transform(obj[k], v)];
     }
 }
-function* _validateUpdates(updates, validator) {
+function* _validateDictionaryUpdates(updates, validator) {
     const feedbacks = new Map();
     for (const [key, value] of Object.entries(updates)) {
         try {

package/update/hydrations.js

@@ -1,13 +1,13 @@
 import { Delete } from "./Delete.js";
 import { Increment } from "./Increment.js";
 import { ArrayUpdate } from "./ArrayUpdate.js";
-import { ObjectUpdate } from "./ObjectUpdate.js";
+import { DictionaryUpdate } from "./DictionaryUpdate.js";
 import { DataUpdate } from "./DataUpdate.js";
 /** Set of hydrations for all update classes. */
 export const UPDATE_HYDRATIONS = {
     Increment,
     Delete,
     ArrayUpdate,
-    ObjectUpdate,
+    DictionaryUpdate,
     DataUpdate,
 };

package/update/index.d.ts

@@ -2,6 +2,6 @@ export * from "./Update.js";
 export * from "./Delete.js";
 export * from "./Increment.js";
 export * from "./ArrayUpdate.js";
-export * from "./ObjectUpdate.js";
 export * from "./DataUpdate.js";
+export * from "./DictionaryUpdate.js";
 export * from "./hydrations.js";

package/update/index.js

@@ -2,6 +2,6 @@ export * from "./Update.js";
 export * from "./Delete.js";
 export * from "./Increment.js";
 export * from "./ArrayUpdate.js";
-export * from "./ObjectUpdate.js";
 export * from "./DataUpdate.js";
+export * from "./DictionaryUpdate.js";
 export * from "./hydrations.js";