shelving 1.23.0 → 1.25.0

package/db/Database.d.ts

@@ -2,7 +2,7 @@ import { Entry, Observable, Observer, Result, Unsubscriber, ResultsMap, Validata
 import { Transform, Transforms } from "../transform/index.js";
 import type { Provider } from "../provider/Provider.js";
 import { Filters, Sorts, Query } from "../query/index.js";
-import { Write } from "./Write.js";
+import { DocumentWrite, Write, Writes } from "./Write.js";
 /**
  * Combines a database model and a provider.
  *
@@ -18,6 +18,10 @@ export declare class Database<V extends Validators<Datas> = Validators<Datas>> {
     query<K extends Key<V>>(collection: K, filters?: Filters<ValidatorType<V[K]>>, sorts?: Sorts<ValidatorType<V[K]>>, limit?: number | null): DataQuery<ValidatorType<V[K]>>;
     /** Reference a document in a collection in this model. */
     doc<K extends Key<V>>(collection: K, id: string): DataDocument<ValidatorType<V[K]>>;
+    /** Perform a write on this database and return the `Write` instance representing the changes. */
+    write(write: Write): Promise<Write>;
+    /** Perform multiple writes on this database by combining them into a single `Writes` instance representing the changes. */
+    writes(...writes: (Write | undefined)[]): Promise<Writes>;
 }
 /** A documents reference within a specific database. */
 export declare class DataQuery<T extends Data = Data> extends Query<T> implements Observable<Results<T>>, Validatable<Results<T>>, Iterable<Entry<T>> {
@@ -151,13 +155,13 @@ export declare class DataDocument<T extends Data = Data> implements Observable<R
     /** Set, update, or delete this document. */
     write(value: Result<T> | Transform<T>): void | PromiseLike<void>;
     /** Represent a write that sets the complete data of this document in a database. */
-    setter(data: T): Write<T>;
+    setter(data: T): DocumentWrite<T>;
     /** Represent a write that updates this document in a database. */
-    updater(transforms: Transform<T> | Transforms<T>): Write<T>;
+    updater(transforms: Transform<T> | Transforms<T>): DocumentWrite<T>;
     /** Represent a write that deletes this document in a database. */
-    deleter(): Write<T>;
+    deleter(): DocumentWrite<T>;
     /** Represent a write that sets, updates, or deletes this document in a database. */
-    writer(value: Result<T> | Transform<T>): Write<T>;
+    writer(value: Result<T> | Transform<T>): DocumentWrite<T>;
     /** Validate data for this query reference. */
     validate(unsafeData: Data): T;
     toString(): string;

package/db/Database.js

@@ -3,7 +3,7 @@ import { DataTransform, Transform } from "../transform/index.js";
 import { Feedback, InvalidFeedback } from "../feedback/index.js";
 import { Filters, Query, EqualFilter } from "../query/index.js";
 import { DocumentRequiredError, DocumentValidationError, QueryValidationError } from "./errors.js";
-import { Write } from "./Write.js";
+import { DocumentWrite, Writes } from "./Write.js";
 /**
  * Combines a database model and a provider.
  *
@@ -25,6 +25,17 @@ export class Database {
     doc(collection, id) {
         return new DataDocument(this.provider, this.validators[collection], collection, id);
     }
+    /** Perform a write on this database and return the `Write` instance representing the changes. */
+    async write(write) {
+        await write.transform(this);
+        return write;
+    }
+    /** Perform multiple writes on this database by combining them into a single `Writes` instance representing the changes. */
+    async writes(...writes) {
+        const write = new Writes(...writes);
+        await write.transform(this);
+        return write;
+    }
 }
 /** A documents reference within a specific database. */
 export class DataQuery extends Query {
@@ -239,7 +250,7 @@ export class DataDocument {
     }
     /** Represent a write that sets, updates, or deletes this document in a database. */
     writer(value) {
-        return new Write(this, value);
+        return new DocumentWrite(this, value);
     }
     /** Validate data for this query reference. */
     validate(unsafeData) {

package/db/Write.d.ts

@@ -1,10 +1,12 @@
 import { Transform } from "../transform/index.js";
 import { ImmutableArray, Data, Transformable } from "../util/index.js";
 import type { Database, DataDocument } from "./Database.js";
-/** Change transformable. */
-export declare type DatabaseTransformable = Transformable<Database, void | PromiseLike<void>>;
+/** Write to a database. */
+export declare abstract class Write implements Transformable<Database, void | PromiseLike<void>> {
+    abstract transform(db: Database): void | PromiseLike<void>;
+}
 /** Represent a write made to a single document in a database. */
-export declare class Write<T extends Data> implements Transformable<Database, void | PromiseLike<void>> {
+export declare class DocumentWrite<T extends Data> extends Write {
     readonly collection: string;
     readonly id: string;
     readonly value: Data | Transform<Data> | undefined;
@@ -12,17 +14,17 @@ export declare class Write<T extends Data> implements Transformable<Database, vo
     transform(db: Database): Promise<void>;
 }
 /**
- * Represent a list of writes made to a set of documents in a database.
+ * Represent a list of writes made to a database.
  * - Sets of writes are predictable and repeatable, so unpredictable operations like `create()` and query operations are not supported.
  * - Every write must be applied to a specific database document in a specific collection and are applied in the specified order.
  */
-export declare class Writes implements Transformable<Database, void | PromiseLike<void>> {
-    readonly writes: ImmutableArray<Write<Data>>;
-    constructor(...writes: Write<Data>[]);
+export declare class Writes extends Write {
+    readonly writes: ImmutableArray<Write>;
+    constructor(...writes: (Write | undefined)[]);
     transform(db: Database): Promise<void>;
 }
 /** Set of hydrations for all change classes. */
-export declare const DATABASE_HYDRATIONS: {
-    changes: typeof Writes;
-    change: typeof Write;
+export declare const WRITE_HYDRATIONS: {
+    writes: typeof Writes;
+    write: typeof DocumentWrite;
 };

package/db/Write.js

@@ -1,7 +1,11 @@
-import { transform } from "../util/index.js";
-/** Represent a write made to a single document in a database. */
+import { transform, IS_DEFINED } from "../util/index.js";
+/** Write to a database. */
 export class Write {
+}
+/** Represent a write made to a single document in a database. */
+export class DocumentWrite extends Write {
     constructor({ collection, id }, value) {
+        super();
         this.collection = collection;
         this.id = id;
         this.value = value;
@@ -11,13 +15,14 @@ export class Write {
     }
 }
 /**
- * Represent a list of writes made to a set of documents in a database.
+ * Represent a list of writes made to a database.
  * - Sets of writes are predictable and repeatable, so unpredictable operations like `create()` and query operations are not supported.
  * - Every write must be applied to a specific database document in a specific collection and are applied in the specified order.
  */
-export class Writes {
+export class Writes extends Write {
     constructor(...writes) {
-        this.writes = writes;
+        super();
+        this.writes = writes.filter(IS_DEFINED);
     }
     async transform(db) {
         for (const writes of this.writes)
@@ -25,8 +30,8 @@ export class Writes {
     }
 }
 /** Set of hydrations for all change classes. */
-export const DATABASE_HYDRATIONS = {
-    changes: Writes,
-    change: Write,
+export const WRITE_HYDRATIONS = {
+    writes: Writes,
+    write: DocumentWrite,
 };
-DATABASE_HYDRATIONS;
+WRITE_HYDRATIONS;

package/package.json

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

package/stream/State.d.ts

@@ -14,8 +14,8 @@ export declare type AnyState = State<any>;
  * */
 export interface State<T> {
     to(): State<T>;
-    derive<TT>(deriver: Transformer<T, TT>): State<TT>;
-    deriveAsync<TT>(deriver: Transformer<T, Promise<TT>>): State<TT>;
+    derive<TT>(transformer: Transformer<T, TT>): State<TT>;
+    deriveAsync<TT>(transformer: Transformer<T, PromiseLike<TT>>): State<TT>;
 }
 export declare class State<T> extends Stream<T> {
     static [Symbol.species]: typeof State;

package/stream/Stream.d.ts

@@ -49,7 +49,7 @@ export declare class Stream<T> implements Observer<T>, Observable<T> {
     derive<TT>(transformer: Transformer<T, TT>): Stream<T>;
     /** Derive a new stream from this stream using an async transformer. */
     deriveAsync<O extends AnyStream>(transformer: Transformer<T, Promise<ObserverType<O>>>, target: O): O;
-    deriveAsync<TT>(transformer: Transformer<T, Promise<TT>>): Stream<T>;
+    deriveAsync<TT>(transformer: Transformer<T, PromiseLike<TT>>): Stream<T>;
     /**
      * Subscribe to this stream and return an unsubscriber function.
      * - Allows either an `Observer` object or  separate `next()`, `error()` and `complete()` functions.

package/transform/DataTransform.d.ts

@@ -13,10 +13,13 @@ export declare type Transforms<T extends Data> = {
 /** Set of transforms that can be appled to an object's properties. */
 export declare class DataTransform<T extends Data> extends Transform<T> implements Iterable<Prop<Transforms<T>>> {
     readonly transforms: Transforms<T>;
-    constructor(transforms: Transforms<T>);
+    constructor(transforms?: Transforms<T>);
     transform(existing: T): T;
-    /** Return a new object with the specified additional transform. */
-    prop<K extends Key<T>>(key: K, transform: T[K] | Transform<T[K]>): this;
+    /**
+     * Return a new object with the specified additional transform.
+     * - If `key` is `undefined` the prop is skipped to make it easy to make conditional data transforms.
+     */
+    prop<K extends Key<T>>(key: K | undefined, transform: T[K] | Transform<T[K]>): this;
     /** Return a new object with the specified additional transforms. */
     props(transforms: Transforms<T>): this;
     /** Iterate over the transforms in this object. */

package/transform/DataTransform.js

@@ -2,15 +2,20 @@ import { transformData } from "../util/index.js";
 import { Transform } from "./Transform.js";
 /** Set of transforms that can be appled to an object's properties. */
 export class DataTransform extends Transform {
-    constructor(transforms) {
+    constructor(transforms = {}) {
         super();
         this.transforms = transforms;
     }
     transform(existing) {
         return transformData(existing, this.transforms);
     }
-    /** Return a new object with the specified additional transform. */
+    /**
+     * Return a new object with the specified additional transform.
+     * - If `key` is `undefined` the prop is skipped to make it easy to make conditional data transforms.
+     */
     prop(key, transform) {
+        if (key === undefined)
+            return this;
         return { __proto__: Object.getPrototypeOf(this), ...this, transforms: { ...this.transforms, [key]: transform } };
     }
     /** Return a new object with the specified additional transforms. */

package/util/transform.d.ts

@@ -9,6 +9,8 @@ export interface Transformable<I, O> {
 }
 /** Any applier (useful for `extends AnyTransformr` clauses). */
 export declare type AnyTransformable = Transformable<any, any>;
+/** Is an unknown value a derivable. */
+export declare const isApplier: <T extends AnyTransformable>(v: unknown) => v is T;
 /** Function that takes an input value and returns a value transformed from it, or an applier with matching arguments. */
 export declare type Transformer<I, O> = Transformable<I, O> | ((input: I) => O) | O;
 /** Any transformer (useful for `extends AnyTransformr` clauses). */
@@ -17,31 +19,18 @@ export declare type AnyTransformer = Transformer<any, any>;
 export declare type TransformedType<T extends AnyTransformer> = T extends Transformer<unknown, infer TT> ? TT : never;
 /** Is an unknown value a transformer. */
 export declare const isTransformer: <T extends unknown>(v: unknown) => v is T;
-/** Is an unknown value a derivable. */
-export declare const isTransformable: <T extends AnyTransformable>(v: unknown) => v is T;
 /** Transform a value using a transformer. */
 export declare function transform<I, O>(input: I, transformer: (v: I) => O): O;
 export declare function transform<I, O>(input: I, transformer: Transformer<I, O>): O;
 /**
  * Apply a transformer to each item in a set of items and yield the transformed item.
- *
  * @yield Transformed items after calling `transformer()` on each.
- * @returns Number of items that changed.
  */
 export declare function transformItems<I, O>(items: Iterable<I>, transformer: (input: I) => O): Iterable<O>;
 export declare function transformItems<I, O>(items: Iterable<I>, transformer: Transformer<I, O>): Iterable<O>;
 /**
  * Apply a transformer to each item in an array and return the transformed array.
- *
- * @param arr The input array or map-like object or iterable to iterate over.
- * @param mapper Mapping function that receives the value and key and returns the corresponding value.
- * - Mapper can return a promise. If it does will return a Promise that resolves once every value has resolved.
- * - Return the `SKIP` symbol from the mapper to skip that property and not include it in the output object.
- * - `SKIP` is useful because using `filter(Boolean)` doesn't currently filter in TypeScript (and requires another loop anyway).
- * - Mapper can be a non-function static value and all the values will be set to that value.
- *
- * @return The mapped array.
- * - Immutable so if the values don't change then the same instance will be returned.
+ * @return The transformed array.
  */
 export declare function transformArray<T extends ImmutableArray>(arr: T, transformer: Transformer<ArrayType<T>, ArrayType<T>>): T;
 export declare function transformArray<I, O>(arr: Iterable<I>, transformer: (v: I) => O): ImmutableArray<O>;

package/util/transform.js

@@ -1,12 +1,12 @@
 import { isFunction } from "./function.js";
 import { toProps, isData } from "./data.js";
 import { WatchIterator } from "./iterate.js";
-/** Is an unknown value a transformer. */
-export const isTransformer = (v) => typeof v === "function" || isTransformable(v);
 /** Is an unknown value a derivable. */
-export const isTransformable = (v) => isData(v) && typeof v.transform === "function";
+export const isApplier = (v) => isData(v) && typeof v.transform === "function";
+/** Is an unknown value a transformer. */
+export const isTransformer = (v) => typeof v === "function" || isApplier(v);
 export function transform(input, transformer) {
-    return isFunction(transformer) ? transformer(input) : isTransformable(transformer) ? transformer.transform(input) : transformer;
+    return isFunction(transformer) ? transformer(input) : isApplier(transformer) ? transformer.transform(input) : transformer;
 }
 export function* transformItems(items, transformer) {
     for (const item of items)