shelving 1.17.0 → 1.18.0

package/api/Resource.d.ts

@@ -1,38 +1,34 @@
-import type { Arguments, AsyncFetcher, Validator } from "../util/index.js";
+import { Validator, Validatable } from "../util/index.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions..
  *
  * @param payload The `Validator` the payload must conform to (defaults to `undefined` if not specified).
  * @param returns The `Validator` the function's returned value must conform to (defaults to `undefined` if not specified).
  */
-export declare class Resource<P, R> {
+export declare class Resource<P = unknown, R = void> implements Validatable<R> {
     static create<X, Y>(payload: Validator<X>, result: Validator<Y>): Resource<X, Y>;
     static create<Y>(payload: undefined, result: Y): Resource<undefined, Y>;
-    static create<X>(payload: Validator<X>, result?: undefined): Resource<X, undefined>;
-    static create(payload?: undefined, result?: undefined): Resource<undefined, undefined>;
-    /** Expose the `P` internal payload type of this resource. */
-    readonly PAYLOAD: P;
-    /** Expose the `R` internal result type of this resource. */
-    readonly RESULT: R;
+    static create<X>(payload: Validator<X>, result?: undefined): Resource<X, void>;
+    static create(payload?: undefined, result?: undefined): Resource<undefined, void>;
     /** Payload validator. */
     readonly payload: Validator<P>;
     /** Result validator. */
     readonly result: Validator<R>;
     protected constructor(payload: Validator<P>, result: Validator<R>);
     /**
-     * Call a resource of this type, with a payload, and return the (async) result.
-     * - Validates the payload (before dispatching).
-     * - Validates the result (after dispatching).
+     * Validate a payload for this resource.
      *
-     * @param resource A resource function corresponding to the type of this resource.
-     * @param payload The payload to send to the resource (validated against the payload validator).
-     * @param ...args Any additional arguments to send to the resource.
-     *
-     * @returns The result returned from the resource (validated against the result validator).
+     */
+    validatePayload(unsafePayload: unknown): P;
+    /**
+     * Validate a result for this resource.
      *
-     * @throws InvalidFeedback If the payload could not be validated.
-     * @throws unknown Anything the function itself throws is thrown.
-     * @throws ValidationError If the result could not be validated.
+     * @returns The validated payload for this resource.
+     * @throws ValidationError if the result could not be validated.
      */
-    call<A extends Arguments>(resource: AsyncFetcher<R, [P, ...A]>, payload: P, ...args: A): Promise<R>;
+    validate(unsafeResult: unknown): R;
 }
+/** Extract the payload type from a `Resource`. */
+export declare type PayloadType<X extends Resource> = X extends Resource<infer Y, unknown> ? Y : never;
+/** Extract the result type from a `Resource`. */
+export declare type ResourceType<X extends Resource> = X extends Resource<unknown, infer Y> ? Y : never;

package/api/Resource.js

@@ -1,5 +1,8 @@
-import { Feedback, ValidationError } from "../util/index.js";
-const UNDEFINED_SCHEMA = { validate: () => undefined };
+import { UNDEFINED, validate } from "../util/index.js";
+import { Feedback, throwFeedback } from "../feedback/index.js";
+import { ResourceValidationError } from "./errors.js";
+/** Validator that always returns void/undefined. */
+const UNDEFINED_VALIDATOR = UNDEFINED;
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions..
  *
@@ -7,41 +10,33 @@ const UNDEFINED_SCHEMA = { validate: () => undefined };
  * @param returns The `Validator` the function's returned value must conform to (defaults to `undefined` if not specified).
  */
 export class Resource {
+    // Protected to require use of `Resource.create()`
     constructor(payload, result) {
-        /** Expose the `P` internal payload type of this resource. */
-        this.PAYLOAD = undefined; // eslint-disable-line @typescript-eslint/no-explicit-any
-        /** Expose the `R` internal result type of this resource. */
-        this.RESULT = undefined; // eslint-disable-line @typescript-eslint/no-explicit-any
         this.payload = payload;
         this.result = result;
     }
-    static create(payload = UNDEFINED_SCHEMA, result = UNDEFINED_SCHEMA) {
+    static create(payload = UNDEFINED_VALIDATOR, result = UNDEFINED_VALIDATOR) {
         return new Resource(payload, result);
     }
     /**
-     * Call a resource of this type, with a payload, and return the (async) result.
-     * - Validates the payload (before dispatching).
-     * - Validates the result (after dispatching).
+     * Validate a payload for this resource.
      *
-     * @param resource A resource function corresponding to the type of this resource.
-     * @param payload The payload to send to the resource (validated against the payload validator).
-     * @param ...args Any additional arguments to send to the resource.
-     *
-     * @returns The result returned from the resource (validated against the result validator).
+     */
+    validatePayload(unsafePayload) {
+        return throwFeedback(validate(unsafePayload, this.payload));
+    }
+    /**
+     * Validate a result for this resource.
      *
-     * @throws InvalidFeedback If the payload could not be validated.
-     * @throws unknown Anything the function itself throws is thrown.
-     * @throws ValidationError If the result could not be validated.
+     * @returns The validated payload for this resource.
+     * @throws ValidationError if the result could not be validated.
      */
-    async call(resource, payload, ...args) {
-        const result = await resource(this.payload.validate(payload), ...args);
+    validate(unsafeResult) {
         try {
-            return this.result.validate(result);
+            return validate(unsafeResult, this.result);
         }
         catch (thrown) {
-            if (thrown instanceof Feedback)
-                throw new ValidationError("Resource returned invalid result", thrown);
-            throw thrown;
+            throw thrown instanceof Feedback ? new ResourceValidationError(this, thrown) : thrown;
         }
     }
 }

package/api/errors.d.ts

@@ -0,0 +1,8 @@
+import { Feedback } from "../feedback/index.js";
+import { ValidationError } from "../error/index.js";
+import type { Resource } from "./Resource.js";
+/** Thrown if an API `Resource` can't validate. */
+export declare class ResourceValidationError<P, R> extends ValidationError {
+    readonly resource: Resource<P, R>;
+    constructor(resource: Resource<P, R>, feedback: Feedback);
+}

package/api/errors.js

@@ -0,0 +1,9 @@
+import { ValidationError } from "../error/index.js";
+/** Thrown if an API `Resource` can't validate. */
+export class ResourceValidationError extends ValidationError {
+    constructor(resource, feedback) {
+        super(`Invalid result for resource`, feedback);
+        this.resource = resource;
+    }
+}
+ResourceValidationError.prototype.name = "ResourceValidationError";

package/db/Change.d.ts

@@ -1,53 +1,39 @@
-import type { Datas, ImmutableArray, Transforms } from "../util/index.js";
-import type { Database } from "./Database.js";
+import { Transforms, Transform } from "../transform/index.js";
+import { Datas, ImmutableArray, Key } from "../util/index.js";
+import type { Database, DatabaseDocument } from "./Database.js";
 /** A single change that can be made to a database. */
 export declare abstract class Change<T extends Datas> {
     /** Apply this change to a database. */
     abstract apply(db: Database<T>): void | Promise<void>;
 }
-/** A change that sets the entire data of a document in a database. */
-export declare class SetChange<T extends Datas, K extends keyof T & string> extends Change<T> {
-    readonly collection: K;
+/** A change that writes a document in a database. */
+export declare class Write<D extends Datas, C extends Key<D>> extends Change<D> {
+    static on<X extends Datas, Y extends Key<X>>({ collection, id }: DatabaseDocument<X, Y>, value: X[Y] | Transform<X[Y]> | undefined): Write<X, Y>;
+    readonly collection: C;
     readonly id: string;
-    readonly data: T[K];
-    constructor(collection: K, id: string, data: T[K]);
-    apply(db: Database<T>): void | Promise<void>;
-}
-/** A change that updates the value of a document in a database. */
-export declare class UpdateChange<T extends Datas, K extends keyof T & string> extends Change<T> {
-    readonly collection: K;
-    readonly id: string;
-    readonly transforms: Transforms<T[K]>;
-    constructor(collection: K, id: string, transforms: Transforms<T[K]>);
-    apply(db: Database<T>): void | Promise<void>;
-}
-/** A change that deletes a document from a database. */
-export declare class DeleteChange<T extends Datas, K extends keyof T & string> extends Change<T> {
-    readonly collection: K;
-    readonly id: string;
-    constructor(collection: K, id: string);
-    apply(db: Database<T>): void | Promise<void>;
+    readonly value: D[C] | Transform<D[C]> | undefined;
+    constructor(collection: C, id: string, value: D[C] | Transform<D[C]> | undefined);
+    apply(db: Database<D>): void | Promise<void>;
 }
 /**
- * Set of changes that can be applied to documents in a database.
+ * Set of writes that can be applied to documents in a database.
  * - Sets of changes are predictable and repeatable, so unpredictable operations like `create()` and query operations are not supported.
  * - Every change must be applied to a specific database document in a specific collection.
  */
-export declare class Changes<T extends Datas> extends Change<T> {
-    readonly changes: ImmutableArray<Change<T>>;
-    constructor(...changes: ImmutableArray<Change<T>>);
-    /** Return a new `Changes` instance with an additional `SetChange` instance in its changes list. */
-    set<K extends keyof T & string>(collection: K, id: string, data: T[K]): this;
-    /** Return a new `Changes` instance with an additional `UpdateChange` instance in its changes list. */
-    update<K extends keyof T & string>(collection: K, id: string, transforms: Transforms<T[K]>): this;
-    /** Return a new `Changes` instance with an additional `DeleteChange` instance in its changes list. */
-    delete<K extends keyof T & string>(collection: K, id: string): this;
-    apply(db: Database<T>): Promise<void>;
+export declare class Writes<D extends Datas> extends Change<D> {
+    static on<X extends Datas>(db: Database<X>, ...changes: ImmutableArray<Change<X>>): Writes<X>;
+    readonly changes: ImmutableArray<Change<D>>;
+    constructor(...changes: ImmutableArray<Change<D>>);
+    /** Return a new `Changes` instance with an additional `Write` instance in its changes list. */
+    set<C extends Key<D>>({ collection, id }: DatabaseDocument<D, C>, data: D[C]): this;
+    /** Return a new `Changes` instance with an additional `Write` instance in its changes list. */
+    delete<C extends Key<D>>({ collection, id }: DatabaseDocument<D, C>): this;
+    /** Return a new `Changes` instance with an additional `Write` instance in its changes list. */
+    update<C extends Key<D>>({ collection, id }: DatabaseDocument<D, C>, transforms: Transforms<D[C]> | Transform<D[C]>): this;
+    apply(db: Database<D>): Promise<void> | undefined;
 }
 /** Set of hydrations for all change classes. */
 export declare const CHANGE_HYDRATIONS: {
-    changes: typeof Changes;
-    set: typeof SetChange;
-    update: typeof UpdateChange;
-    delete: typeof DeleteChange;
+    writes: typeof Writes;
+    write: typeof Write;
 };

package/db/Change.js

@@ -1,76 +1,66 @@
+import { DataTransform, Transform } from "../transform/index.js";
+import { VOID, isAsync } from "../util/index.js";
 /** A single change that can be made to a database. */
 export class Change {
 }
-/** A change that sets the entire data of a document in a database. */
-export class SetChange extends Change {
-    constructor(collection, id, data) {
+/** A change that writes a document in a database. */
+export class Write extends Change {
+    constructor(collection, id, value) {
         super();
         this.collection = collection;
         this.id = id;
-        this.data = data;
+        this.value = value;
     }
-    apply(db) {
-        // Use an update query (rather than `document.update()` so there's no error thrown if the document doesn't exist).
-        return db.docs(this.collection).is("id", this.id).set(this.data);
-    }
-}
-/** A change that updates the value of a document in a database. */
-export class UpdateChange extends Change {
-    constructor(collection, id, transforms) {
-        super();
-        this.collection = collection;
-        this.id = id;
-        this.transforms = transforms;
+    static on({ collection, id }, value) {
+        return new Write(collection, id, value);
     }
     apply(db) {
-        return db.doc(this.collection, this.id).update(this.transforms);
-    }
-}
-/** A change that deletes a document from a database. */
-export class DeleteChange extends Change {
-    constructor(collection, id) {
-        super();
-        this.collection = collection;
-        this.id = id;
-    }
-    apply(db) {
-        return db.doc(this.collection, this.id).delete();
+        return db.doc(this.collection, this.id).write(this.value);
     }
 }
 /**
- * Set of changes that can be applied to documents in a database.
+ * Set of writes that can be applied to documents in a database.
  * - Sets of changes are predictable and repeatable, so unpredictable operations like `create()` and query operations are not supported.
  * - Every change must be applied to a specific database document in a specific collection.
  */
-export class Changes extends Change {
+export class Writes extends Change {
     constructor(...changes) {
         super();
         this.changes = changes;
     }
-    /** Return a new `Changes` instance with an additional `SetChange` instance in its changes list. */
-    set(collection, id, data) {
-        return { __proto__: Changes.prototype, ...this, changes: [...this.changes, new SetChange(collection, id, data)] };
+    static on(db, ...changes) {
+        return new Writes(...changes);
+    }
+    /** Return a new `Changes` instance with an additional `Write` instance in its changes list. */
+    set({ collection, id }, data) {
+        return { __proto__: Object.getPrototypeOf(this), ...this, changes: [...this.changes, new Write(collection, id, data)] };
     }
-    /** Return a new `Changes` instance with an additional `UpdateChange` instance in its changes list. */
-    update(collection, id, transforms) {
-        return { __proto__: Changes.prototype, ...this, changes: [...this.changes, new UpdateChange(collection, id, transforms)] };
+    /** Return a new `Changes` instance with an additional `Write` instance in its changes list. */
+    delete({ collection, id }) {
+        return { __proto__: Object.getPrototypeOf(this), ...this, changes: [...this.changes, new Write(collection, id, undefined)] };
     }
-    /** Return a new `Changes` instance with an additional `DeleteChange` instance in its changes list. */
-    delete(collection, id) {
-        return { __proto__: Changes.prototype, ...this, changes: [...this.changes, new DeleteChange(collection, id)] };
+    /** Return a new `Changes` instance with an additional `Write` instance in its changes list. */
+    update({ collection, id }, transforms) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            changes: [...this.changes, new Write(collection, id, transforms instanceof Transform ? transforms : new DataTransform(transforms))],
+        };
     }
-    async apply(db) {
-        const changes = [];
-        for (const change of this.changes)
-            changes.push(change.apply(db));
-        await Promise.all(changes);
+    apply(db) {
+        const promises = [];
+        for (const change of this.changes) {
+            const applied = change.apply(db);
+            if (isAsync(applied))
+                promises.push(applied);
+        }
+        if (promises.length)
+            return Promise.all(promises).then(VOID);
     }
 }
 /** Set of hydrations for all change classes. */
 export const CHANGE_HYDRATIONS = {
-    changes: Changes,
-    set: SetChange,
-    update: UpdateChange,
-    delete: DeleteChange,
+    writes: Writes,
+    write: Write,
 };
 CHANGE_HYDRATIONS;

package/db/Database.d.ts

@@ -1,30 +1,178 @@
-import type { Datas, Validators } from "../util/index.js";
-import type { Provider } from "./Provider.js";
-import { Document } from "./Document.js";
-import { Documents } from "./Documents.js";
+import { Dispatcher, Entry, Observable, Observer, Result, Unsubscriber, Datas, Results, Validatable, Validator, Validators, Key, Data, ImmutableMap } from "../util/index.js";
+import { Transform, Transforms } from "../transform/index.js";
+import type { Provider } from "../provider/Provider.js";
+import { Filters, Sorts, Query } from "../query/index.js";
 /**
- * Database: combines a set of document and collection loci for the root level of the database, and links them to a Provider.
+ * Combines a database model and a provider.
  *
  * @param documents Set of loci describing named documents at the root level of the database.
  * @param collections Set of loci describing collections at the root level of the database.
  * @param provider Provider that allows data to be read/written.
  */
-export declare class Database<T extends Datas = Datas> {
-    /** List of schemas validators for the collections in this database. */
-    readonly schemas: Validators<T>;
-    /** The provider that powers this database. */
-    readonly provider: Provider;
-    constructor(schemas: Validators<T>, provider: Provider);
+export declare class Database<D extends Datas> {
+    readonly validators: Validators<D>;
+    readonly provider: Provider<D>;
+    constructor(validators: Validators<D>, provider: Provider<D>);
+    /** Create a query on a collection in this model. */
+    query<C extends Key<D>>(collection: C, filters?: Filters<D[C]>, sorts?: Sorts<D[C]>, limit?: number | null): DatabaseQuery<D, C>;
+    /** Reference a document in a collection in this model. */
+    doc<C extends Key<D>>(collection: C, id: string): DatabaseDocument<D, C>;
+}
+/** A documents reference within a specific database. */
+export declare class DatabaseQuery<D extends Datas, C extends Key<D>> extends Query<D[C]> implements Observable<Results<D[C]>>, Validatable<Results<D[C]>>, Iterable<Entry<D[C]>> {
+    readonly db: Database<D>;
+    readonly validator: Validator<D[C]>;
+    readonly collection: C;
+    constructor(db: Database<D>, collection: C, filters?: Filters<D[C]>, sorts?: Sorts<D[C]>, limit?: number | null);
+    /** Reference a document in this query's collection. */
+    doc(id: string): DatabaseDocument<D, C>;
+    /**
+     * Create a new document with a random ID.
+     * - Created document is guaranteed to have a unique ID.
+     *
+     * @param data Complete data to set the document to.
+     * @return String ID for the created document (possibly promised).
+     */
+    add(data: D[C]): string | Promise<string>;
+    /**
+     * Get an iterable that yields the results of this entry.
+     * @return Map containing the results.
+     */
+    get results(): Results<D[C]> | Promise<Results<D[C]>>;
+    /**
+     * Read the results of this query into a map.
+     * @return Set of results in `id: data` format (possibly promised).
+     */
+    get map(): ImmutableMap<D[C]> | Promise<ImmutableMap<D[C]>>;
+    /**
+     * Count the number of results of this set of documents.
+     * @return Number of documents in the collection (possibly promised).
+     */
+    get count(): number | Promise<number>;
+    /**
+     * Subscribe to all matching documents.
+     * - `next()` is called once with the initial results, and again any time the results change.
+     *
+     * @param observer Observer with `next`, `error`, or `complete` methods that the document results are reported back to.
+     * @param next Callback that is called once initially and again whenever the results change.
+     * @param error Callback that is called if an error occurs.
+     * @param complete Callback that is called when the subscription is done.
+     *
+     * @return Function that ends the subscription.
+     */
+    subscribe(next: Observer<Results<D[C]>> | Dispatcher<Results<D[C]>>, error?: Dispatcher<Error | unknown>, complete?: Dispatcher<void>): Unsubscriber;
+    /**
+     * Get an entry for the first document matching this query.
+     * @return Entry in `[id, data]` format for the first document, or `undefined` if there are no matching documents (possibly promised).
+     */
+    get first(): Entry<D[C]> | undefined | Promise<Entry<D[C]> | undefined>;
+    /**
+     * Set all matching documents to the same exact value.
+     *
+     * @param data Complete data to set the document to.
+     * @return Nothing (possibly promised).
+     */
+    set(data: D[C]): void | Promise<void>;
+    /**
+     * Update all matching documents with the same partial value.
+     *
+     * @param transform `Transform` instance or set of transforms to apply to every matching document.
+     * - Not all transforms may be supported by all providers.
+     *
+     * @return Nothing (possibly promised).
+     */
+    update(transform: Transform<D[C]> | Transforms<D[C]>): void | Promise<void>;
+    /**
+     * Delete all matching documents.
+     * @return Nothing (possibly promised).
+     */
+    delete(): void | Promise<void>;
+    /**
+     * Combine `set()`, `update()`, `delete()` into a single method.
+     * @return Nothing (possibly promised).
+     */
+    write(value: Result<D[C]> | Transform<D[C]>): void | Promise<void>;
+    /** Iterate over the resuls (will throw `Promise` if the results are asynchronous). */
+    [Symbol.iterator](): Iterator<Entry<D[C]>, void>;
+    /** Validate a set of results for this query reference. */
+    validate(unsafeEntries: Results): Results<D[C]>;
+    toString(): string;
+}
+/** A document reference within a specific database. */
+export declare class DatabaseDocument<D extends Datas, C extends Key<D>> implements Observable<Result<D[C]>>, Validatable<D[C]> {
+    readonly db: Database<D>;
+    readonly validator: Validator<D[C]>;
+    readonly collection: C;
+    readonly id: string;
+    constructor(db: Database<D>, collection: C, id: string);
+    /** Create a query on this document's collection. */
+    query(filters?: Filters<D[C]>, sorts?: Sorts<D[C]>, limit?: number | null): DatabaseQuery<D, C>;
+    /** Get an 'optional' reference to this document (uses a `ModelQuery` with an `id` filter). */
+    get optional(): DatabaseQuery<D, C>;
+    /**
+     * Does this document exist?
+     *
+     * @return Document's data, or `undefined` if the document doesn't exist (possibly promised).
+     */
+    get exists(): boolean | Promise<boolean>;
+    /**
+     * Get the result of this document.
+     *
+     * @return Document's data, or `undefined` if the document doesn't exist (possibly promised).
+     */
+    get result(): Result<D[C]> | Promise<Result<D[C]>>;
+    /**
+     * Get the data of this document.
+     * - Useful for destructuring, e.g. `{ name, title } = await documentThatMustExist.asyncData`
+     *
+     * @return Document's data (possibly promised).
+     * @throws RequiredError if the document's result was undefined.
+     */
+    get data(): D[C] | Promise<D[C]>;
+    /**
+     * Subscribe to the result of this document (indefinitely).
+     * - `next()` is called once with the initial result, and again any time the result changes.
+     *
+     * @param observer Observer with `next`, `error`, or `complete` methods.
+     * @param next Callback that is called once initially and again whenever the result changes.
+     * @param error Callback that is called if an error occurs.
+     * @param complete Callback that is called when the subscription is done.
+     *
+     * @return Function that ends the subscription.
+     */
+    subscribe(next: Observer<Result<D[C]>> | Dispatcher<Result<D[C]>>, error?: Dispatcher<Error | unknown>, complete?: Dispatcher<void>): Unsubscriber;
+    /**
+     * Set the complete data of this document.
+     *
+     * @param data Complete data to set the document to.
+     *
+     * @return Nothing (possibly promised).
+     */
+    set(data: D[C]): void | Promise<void>;
+    /**
+     * Update this document with partial data.
+     * - If the document exists, merge the partial data into it.
+     * - If the document doesn't exist, throw an error.
+     *
+     * @param transforms `Transform` instance or set of transforms to apply to the existing document.
+     * - Not all transforms may be supported by all providers.
+     *
+     * @return Nothing (possibly promised).
+     * @throws Error If the document does not exist (ideally a `RequiredError` but may be provider-specific).
+     */
+    update(transforms: Transform<D[C]> | Transforms<D[C]>): void | Promise<void>;
     /**
-     * Get a `Documents` ref for a set of documents in a collection in this database.
-     * @param name Collection name, e.g. `puppies`
-     * @example `db.docs("dogs").doc("fido").get()`
+     * Delete this document.
+     * - Will not throw an error if the document doesn't exist.
+     *
+     * @return Nothing (possibly promised).
      */
-    docs<C extends keyof T & string>(collection: C): Documents<T[C]>;
+    delete(): void | Promise<void>;
     /**
-     * Get a `Document` ref for a document in a collection in this database.
-     * @param name Document name, e.g. `fido`
-     * @example `db.doc("dogs", "fido").get()`
+     * Combine `set()`, `update()`, `delete()` into a single method.
      */
-    doc<C extends keyof T & string>(collection: C, id: string): Document<T[C]>;
+    write(value: Result<D[C]> | Transform<D[C]>): void | Promise<void>;
+    /** Validate data for this query reference. */
+    validate(unsafeData: Data): D[C];
+    toString(): string;
 }