shelving 1.27.0 → 1.28.0

package/db/Database.d.ts

@@ -1,8 +1,8 @@
-import { Entry, Observable, Observer, Result, Unsubscriber, ResultsMap, Validatable, Validator, Key, Data, Results, Datas, Validators, ValidatorType, Dispatcher } from "../util/index.js";
+import { Entry, Observable, Observer, Result, Unsubscriber, ResultsMap, Validatable, Validator, Key, Data, Results, Datas, Validators, ValidatorType, Dispatcher, Nullish } from "../util/index.js";
 import { PropUpdates, Update } from "../update/index.js";
 import type { Provider } from "../provider/Provider.js";
 import { Filters, Sorts, Query } from "../query/index.js";
-import { DocumentDelete, DocumentSet, DocumentUpdate, Write, Writes } from "./Write.js";
+import { DocumentDelete, DocumentSet, DocumentUpdate, Write } from "./Write.js";
 /**
  * Combines a database model and a provider.
  *
@@ -18,10 +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>;
+    /** Create a writer for this database from a set of separate writes. */
+    writer(...writes: Nullish<Write>[]): Write;
+    /** Perform one or more writes on this database and return the `Writes` instance representing the combined changes. */
+    write(...writes: Nullish<Write>[]): Promise<Write>;
 }
 /** 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>> {

package/db/Database.js

@@ -1,4 +1,4 @@
-import { callAsync, getFirstItem, throwAsync, validate, toMap, countItems, TransformObserver, } from "../util/index.js";
+import { callAsync, getFirstItem, throwAsync, validate, toMap, countItems, TransformObserver, NOT_NULLISH, } from "../util/index.js";
 import { DataUpdate, Update } from "../update/index.js";
 import { Feedback, InvalidFeedback } from "../feedback/index.js";
 import { Filters, Query, EqualFilter } from "../query/index.js";
@@ -25,14 +25,13 @@ 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;
+    /** Create a writer for this database from a set of separate writes. */
+    writer(...writes) {
+        return new Writes(...writes.filter(NOT_NULLISH));
     }
-    /** 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);
+    /** Perform one or more writes on this database and return the `Writes` instance representing the combined changes. */
+    async write(...writes) {
+        const write = new Writes(...writes.filter(NOT_NULLISH));
         await write.transform(this);
         return write;
     }

package/db/Write.d.ts

@@ -12,7 +12,7 @@ export declare abstract class Write implements Transformable<Database, void | Pr
  */
 export declare class Writes extends Write {
     readonly writes: ImmutableArray<Write>;
-    constructor(...writes: (Write | undefined)[]);
+    constructor(...writes: Write[]);
     transform(db: Database): Promise<void>;
 }
 /** Represent a write made to a single document in a database. */

package/db/Write.js

@@ -1,5 +1,5 @@
 import { DataUpdate, Update } from "../update/index.js";
-import { transform, IS_DEFINED } from "../util/index.js";
+import { transform } from "../util/index.js";
 /** Represent a write made to a database. */
 export class Write {
 }
@@ -11,7 +11,7 @@ export class Write {
 export class Writes extends Write {
     constructor(...writes) {
         super();
-        this.writes = writes.filter(IS_DEFINED);
+        this.writes = writes;
     }
     async transform(db) {
         for (const writes of this.writes)

package/package.json

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

package/stream/DataState.d.ts

@@ -1,9 +1,24 @@
-import { Key, Data, PropTransformers } from "../util/index.js";
+import { Key, Data, PropTransformers, Result } from "../util/index.js";
 import { State } from "./State.js";
-/** State that stores an array and has additional methods to help with that. */
+/** State that stores a data object and has additional methods to help with that. */
 export declare class DataState<T extends Data> extends State<T> {
+    /** Get the data value of this state. */
+    get data(): T;
     /** Set a prop in this object to a new value. */
     set<K extends Key<T>>(key: K, value: T[K]): void;
     /** Update several props in this object. */
     update(updates: PropTransformers<T>): void;
 }
+/** State that stores an optional data object and has additional methods to help with that. */
+export declare class ResultState<T extends Data> extends State<Result<T>> {
+    /** Get the result value of this state. */
+    get result(): Result<T>;
+    /** Get current data value of this state (or throw `Promise` that resolves to the next required value). */
+    get data(): T;
+    /** Set a prop in this object to a new value. */
+    set<K extends Key<T>>(key: K, value: T[K]): void;
+    /** Update several props in this object. */
+    update(updates: PropTransformers<T>): void;
+    /** Delete this result. */
+    delete(): void;
+}

package/stream/DataState.js

@@ -1,13 +1,44 @@
-import { withProp, transformData } from "../util/index.js";
+import { withProp, transformData, NOERROR, LOADING, awaitNext, getData } from "../util/index.js";
 import { State } from "./State.js";
-/** State that stores an array and has additional methods to help with that. */
+/** State that stores a data object and has additional methods to help with that. */
 export class DataState extends State {
+    /** Get the data value of this state. */
+    get data() {
+        return this.value;
+    }
     /** Set a prop in this object to a new value. */
     set(key, value) {
-        this.next(withProp(this.value, key, value));
+        this.next(withProp(this.data, key, value));
     }
     /** Update several props in this object. */
     update(updates) {
-        this.next(transformData(this.value, updates));
+        this.next(transformData(this.data, updates));
+    }
+}
+/** State that stores an optional data object and has additional methods to help with that. */
+export class ResultState extends State {
+    /** Get the result value of this state. */
+    get result() {
+        return this.value;
+    }
+    /** Get current data value of this state (or throw `Promise` that resolves to the next required value). */
+    get data() {
+        if (this.reason !== NOERROR)
+            throw this.reason;
+        if (this._value === LOADING)
+            throw awaitNext(this).then(getData);
+        return getData(this._value);
+    }
+    /** Set a prop in this object to a new value. */
+    set(key, value) {
+        this.next(withProp(this.data, key, value));
+    }
+    /** Update several props in this object. */
+    update(updates) {
+        this.next(transformData(this.data, updates));
+    }
+    /** Delete this result. */
+    delete() {
+        this.next(undefined);
     }
 }

package/stream/State.d.ts

@@ -28,8 +28,6 @@ export declare class State<T> extends Stream<T> {
     /** Most recently dispatched value (or throw `Promise` that resolves to the next value). */
     get value(): T;
     protected _value: T | typeof LOADING;
-    /** Get current required value (or throw `Promise` that resolves to the next required value). */
-    get data(): Exclude<T, null | undefined>;
     /** Is there a current value, or is it still loading. */
     get loading(): boolean;
     /** Apply a transformer to this state. */

package/stream/State.js

@@ -1,5 +1,5 @@
 var _a;
-import { LOADING, NOERROR, dispatchNext, dispatchError, dispatchComplete, transform, getRequired, awaitNext, } from "../util/index.js";
+import { LOADING, NOERROR, dispatchNext, dispatchError, dispatchComplete, transform, awaitNext, } from "../util/index.js";
 import { Stream } from "./Stream.js";
 export class State extends Stream {
     constructor() {
@@ -22,14 +22,6 @@ export class State extends Stream {
             throw awaitNext(this);
         return this._value;
     }
-    /** Get current required value (or throw `Promise` that resolves to the next required value). */
-    get data() {
-        if (this.reason !== NOERROR)
-            throw this.reason;
-        if (this._value === LOADING)
-            throw awaitNext(this).then(getRequired);
-        return getRequired(this._value);
-    }
     /** Is there a current value, or is it still loading. */
     get loading() {
         return this._value === LOADING;

package/util/data.d.ts

@@ -25,9 +25,6 @@ export declare const isData: <T extends Data>(value: unknown) => value is T;
 /** Turn a data object into an array of entries (if it isn't one already). */
 export declare function toProps<T extends Data>(input: T): ImmutableArray<Prop<T>>;
 export declare function toProps<T extends Data>(input: Partial<T>): ImmutableArray<Prop<T>>;
-/** Get a required value (returns value or throws `RequiredError` if value is `null` or `undefined`). */
-export declare function getRequired<T>(v: T): Exclude<T, null | undefined>;
-export declare function getRequired<T>(v: T | null | undefined): T;
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export declare function getData<T extends Data>(result: Result<T>): T;
 /**

package/util/data.js

@@ -4,11 +4,6 @@ export const isData = (value) => typeof value === "object" && value !== null;
 export function toProps(input) {
     return Object.entries(input);
 }
-export function getRequired(v) {
-    if (v === undefined || v === null)
-        throw new RequiredError(v === null ? "Required value is null" : "Required value is undefined");
-    return v;
-}
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export function getData(result) {
     if (!result)

package/util/null.d.ts

@@ -4,3 +4,14 @@ export declare const IS_NULL: (v: unknown) => v is null;
 export declare const NOT_NULL: <T>(v: T | null) => v is T;
 /** Function that always returns null. */
 export declare const NULL: () => null;
+/** Nullish is `null` or `undefined` */
+export declare type Nullish<T> = T | null | undefined;
+/** Nullish is `null` or `undefined` */
+export declare type NotNullish<T> = Exclude<T, null | undefined>;
+/** Is a value nullish? */
+export declare const IS_NULLISH: <T>(v: Nullish<T>) => v is null | undefined;
+/** Is a value nullish? */
+export declare const NOT_NULLISH: <T>(v: Nullish<T>) => v is T;
+/** Get a required value (returns value or throws `RequiredError` if value is `null` or `undefined`). */
+export declare function getRequired<T>(v: T): NotNullish<T>;
+export declare function getRequired<T>(v: Nullish<T>): T;

package/util/null.js

@@ -1,6 +1,16 @@
+import { RequiredError } from "../error/index.js";
 /** Is a value null? */
 export const IS_NULL = (v) => v === null;
 /** Is a value not null? */
 export const NOT_NULL = (v) => v !== null;
 /** Function that always returns null. */
 export const NULL = () => null;
+/** Is a value nullish? */
+export const IS_NULLISH = (v) => v === null || v === undefined;
+/** Is a value nullish? */
+export const NOT_NULLISH = (v) => v !== null && v !== undefined;
+export function getRequired(v) {
+    if (v === undefined || v === null)
+        throw new RequiredError("Required value is missing");
+    return v;
+}

package/util/url.d.ts

@@ -1,10 +1,9 @@
+/** Things that can be converted to a URL instance. */
+export declare type PossibleURL = string | URL;
+export declare type PossibleOptionalURL = PossibleURL | null;
+/** Convert a possible URL to a URL or return `null` if conversion fails. */
+export declare function toURL(url: PossibleURL, base?: PossibleOptionalURL): URL | null;
+/** Convert a possible URL to a URL but throw `AssertionError` if conversion fails. */
+export declare function getURL(input: PossibleURL, base?: PossibleOptionalURL): URL;
 /** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export declare const formatUrl: (url: string | URL) => string;
-/**
- * Convert a string to a URL instance or return `null` if we can't.
- * - Automatically prepend `https://` if there's no `:` anywhere.
- *
- * @param url Base
- * @param
- */
-export declare function toURL(url: string | URL, base?: URL | string | undefined): URL | null;
+export declare const formatUrl: (url: PossibleURL) => string;

package/util/url.js

@@ -1,25 +1,26 @@
-import { getRequired } from "./data.js";
-/** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export const formatUrl = (url) => {
-    const { host, pathname } = getRequired(toURL(url));
-    return `${host}${pathname.length > 1 ? pathname : ""}`;
-};
-/**
- * Convert a string to a URL instance or return `null` if we can't.
- * - Automatically prepend `https://` if there's no `:` anywhere.
- *
- * @param url Base
- * @param
- */
-export function toURL(url, base = typeof window === "object" ? window.location.href : undefined) {
+import { AssertionError } from "../error/index.js";
+/** Convert a possible URL to a URL or return `null` if conversion fails. */
+export function toURL(url, base = typeof window === "object" ? window.location.href : null) {
     if (url instanceof URL)
         return url;
     if (!url)
         return null;
     try {
-        return new URL(url, base);
+        return new URL(url, base || undefined);
     }
     catch (e) {
         return null;
     }
 }
+/** Convert a possible URL to a URL but throw `AssertionError` if conversion fails. */
+export function getURL(input, base) {
+    const url = toURL(input, base);
+    if (!url)
+        throw new AssertionError("Invalid URL", input);
+    return url;
+}
+/** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
+export const formatUrl = (url) => {
+    const { host, pathname } = getURL(url);
+    return `${host}${pathname.length > 1 ? pathname : ""}`;
+};