@bodil/bdb 0.1.3 → 0.2.1

package/dist/indices.js

@@ -1,7 +1,10 @@
+/** @internal */
 export class Index {
 }
+/** @internal */
 export class UnitIndex extends Index {
 }
+/** @internal */
 export class CustomIndex {
     constructor(index, makeIndex) {
         this.index = index;
@@ -17,6 +20,7 @@ export class CustomIndex {
         return [value[this.index]];
     }
 }
+/** @internal */
 export class PrimitiveIndex {
     constructor(index) {
         this.index = index;
@@ -31,6 +35,7 @@ export class PrimitiveIndex {
         return [value[this.index]];
     }
 }
+/** @internal */
 export class ArrayIndex {
     constructor(index) {
         this.index = index;
@@ -40,6 +45,7 @@ export class ArrayIndex {
         return value[this.index];
     }
 }
+/** @internal */
 export class CompoundIndex {
     constructor(leftIndex, rightIndex) {
         this.leftIndex = leftIndex;

package/dist/indices.js.map

@@ -1 +1 @@
-{"version":3,"file":"indices.js","sourceRoot":"","sources":["../src/indices.ts"],"names":[],"mappings":"AAIA,MAAM,OAAgB,KAAK;CAK1B;AAED,MAAM,OAAgB,SAA4B,SAAQ,KAAQ;CAEjE;AAED,MAAM,OAAO,WAAW;IAMpB,YACoB,KAAQ,EACR,SAAsC;QADtC,UAAK,GAAL,KAAK,CAAG;QACR,cAAS,GAAT,SAAS,CAA6B;IACvD,CAAC;IAEJ,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,UAAU,CAAC,KAAQ;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/B,CAAC;CACJ;AAED,MAAM,OAAO,cAAc;IAMvB,YAA4B,KAAQ;QAAR,UAAK,GAAL,KAAK,CAAG;IAAG,CAAC;IAExC,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,UAAU,CAAC,KAAQ;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/B,CAAC;CACJ;AAED,MAAM,OAAO,UAAU;IAWnB,YAAY,KAAQ;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAM,CAAC;IAClC,CAAC;CACJ;AAED,MAAM,OAAO,aAAa;IAatB,YAAY,SAAY,EAAE,UAAa;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,GAAG,SAAS,IAAI,UAAU,EAAE,CAAC;IAC7C,CAAC;IAED,UAAU,CAAC,KAAQ;QACf,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;CACJ"}
+{"version":3,"file":"indices.js","sourceRoot":"","sources":["../src/indices.ts"],"names":[],"mappings":"AAIA,gBAAgB;AAChB,MAAM,OAAgB,KAAK;CAK1B;AAED,gBAAgB;AAChB,MAAM,OAAgB,SAA4B,SAAQ,KAAQ;CAEjE;AAED,gBAAgB;AAChB,MAAM,OAAO,WAAW;IAMpB,YACoB,KAAQ,EACR,SAAsC;QADtC,UAAK,GAAL,KAAK,CAAG;QACR,cAAS,GAAT,SAAS,CAA6B;IACvD,CAAC;IAEJ,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,UAAU,CAAC,KAAQ;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/B,CAAC;CACJ;AAED,gBAAgB;AAChB,MAAM,OAAO,cAAc;IAMvB,YAA4B,KAAQ;QAAR,UAAK,GAAL,KAAK,CAAG;IAAG,CAAC;IAExC,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,UAAU,CAAC,KAAQ;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/B,CAAC;CACJ;AAED,gBAAgB;AAChB,MAAM,OAAO,UAAU;IAUnB,YAAY,KAAQ;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAM,CAAC;IAClC,CAAC;CACJ;AAED,gBAAgB;AAChB,MAAM,OAAO,aAAa;IAatB,YAAY,SAAY,EAAE,UAAa;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,GAAG,SAAS,IAAI,UAAU,EAAE,CAAC;IAC7C,CAAC;IAED,UAAU,CAAC,KAAQ;QACf,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,WAAW,CAAC,KAAQ;QAChB,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;CACJ"}

package/dist/query.d.ts

@@ -6,46 +6,49 @@ export declare enum IteratorDirection {
     Ascending = 0,
     Descending = 1
 }
-export declare abstract class Query<A extends object> implements Iterable<Readonly<A>> {
-    abstract [Symbol.iterator](): IterableIterator<Readonly<A>>;
-    abstract signal(): Signal.Computed<Array<Readonly<A>>>;
-    map<B>(mapFn: (item: Readonly<A>) => B): IterableIterator<B>;
-    forEach(action: (item: A) => void): void;
-    toArray(): Array<Readonly<A>>;
+export declare abstract class Query<Document extends object> implements Iterable<Readonly<Document>> {
+    abstract [Symbol.iterator](): IterableIterator<Readonly<Document>>;
+    abstract signal(): Signal.Computed<Array<Readonly<Document>>>;
+    map<B>(mapFn: (item: Readonly<Document>) => B): IterableIterator<B>;
+    forEach(action: (item: Document) => void): void;
+    toArray(): Array<Readonly<Document>>;
 }
-export declare abstract class TableQuery<A extends object, PI extends UnitIndex<A>, Ix extends object> extends Query<A> {
-    table: Table<A, PI, Ix>;
-    constructor(table: Table<A, PI, Ix>);
-    signal(): Signal.Computed<Array<Readonly<A>>>;
+export declare abstract class TableQuery<Document extends object, PI extends UnitIndex<Document>, Ix extends object> extends Query<Document> {
+    /** @ignore */
+    protected table: Table<Document, PI, Ix>;
+    constructor(table: Table<Document, PI, Ix>);
+    signal(): Signal.Computed<Array<Readonly<Document>>>;
+    /**
+     * Delete all documents from the table matching this query.
+     */
     delete(): number;
-    filter(predicate: (item: Readonly<A>) => boolean): ChainQuery<A, PI, Ix>;
-    limit(count: number): ChainQuery<A, PI, Ix>;
+    filter(predicate: (item: Readonly<Document>) => boolean): ChainQuery<Document, PI, Ix>;
+    limit(count: number): ChainQuery<Document, PI, Ix>;
 }
-export declare class IndexQuery<A extends object, PI extends UnitIndex<A>, I extends Index<A>, Ix extends object> extends TableQuery<A, PI, Ix> {
+export declare class IndexQuery<Document extends object, PI extends UnitIndex<Document>, I extends Index<Document>, Ix extends object> extends TableQuery<Document, PI, Ix> {
     private readonly index;
     private readonly indexTable?;
     private readonly isPrimary;
     private start?;
     private skipStart;
     private direction;
-    constructor(table: Table<A, PI, Ix>, indexKey: keyof Ix & string, direction: IteratorDirection, start?: I["keyType"]);
-    [Symbol.iterator](): IterableIterator<Readonly<A>>;
-    reverse(): this;
-    equals(value: I["keyType"]): ArrayQuery<A, PI, Ix>;
+    constructor(table: Table<Document, PI, Ix>, indexKey: keyof Ix & string, direction: IteratorDirection, start?: I["keyType"]);
+    [Symbol.iterator](): IterableIterator<Readonly<Document>>;
+    equals(value: I["keyType"]): ArrayQuery<Document, PI, Ix>;
     below(value: I["keyType"]): this;
     above(value: I["keyType"]): this;
     inclusive(): this;
     max(): Option<I["keyType"]>;
     min(): Option<I["keyType"]>;
 }
-export declare class ChainQuery<A extends object, PI extends UnitIndex<A>, Ix extends object> extends TableQuery<A, PI, Ix> {
+export declare class ChainQuery<Document extends object, PI extends UnitIndex<Document>, Ix extends object> extends TableQuery<Document, PI, Ix> {
     private readonly parent;
     private readonly iterator;
-    constructor(table: Table<A, PI, Ix>, parent: Query<A>, iterator: (parentIterator: IterableIterator<Readonly<A>>) => IterableIterator<Readonly<A>>);
-    [Symbol.iterator](): IterableIterator<Readonly<A>>;
+    constructor(table: Table<Document, PI, Ix>, parent: Query<Document>, iterator: (parentIterator: IterableIterator<Readonly<Document>>) => IterableIterator<Readonly<Document>>);
+    [Symbol.iterator](): IterableIterator<Readonly<Document>>;
 }
-export declare class ArrayQuery<A extends object, PI extends UnitIndex<A>, Ix extends object> extends TableQuery<A, PI, Ix> {
+export declare class ArrayQuery<Document extends object, PI extends UnitIndex<Document>, Ix extends object> extends TableQuery<Document, PI, Ix> {
     private readonly values;
-    constructor(table: Table<A, PI, Ix>, values: Array<Readonly<A>>);
-    [Symbol.iterator](): IterableIterator<Readonly<A>>;
+    constructor(table: Table<Document, PI, Ix>, values: Array<Readonly<Document>>);
+    [Symbol.iterator](): IterableIterator<Readonly<Document>>;
 }

package/dist/query.js

@@ -53,6 +53,9 @@ export class Query {
         return Array.from(this);
     }
 }
+function arraysEqual(a, b) {
+    return a.length === b.length && a.every((v, i) => Object.is(v, b[i]));
+}
 export class TableQuery extends Query {
     constructor(table) {
         super();
@@ -62,10 +65,13 @@ export class TableQuery extends Query {
         return Signal.computed(() => {
             this.table.changed.get();
             return Array.from(this);
-        });
+        }, { equals: arraysEqual });
     }
+    /**
+     * Delete all documents from the table matching this query.
+     */
     delete() {
-        return this.table.delete(...Array.from(this));
+        return this.table.delete(...Array.from(this).map((doc) => this.table.primaryIndex.extractKey(doc)));
     }
     filter(predicate) {
         return new ChainQuery(this.table, this, (iter) => Iterator.from(iter).filter(predicate));
@@ -95,16 +101,6 @@ export class IndexQuery extends TableQuery {
             ? primaryIndexIterator(this.table.primary, this.direction, this.start, this.skipStart)
             : indexIterator(this.indexTable, this.direction, this.start, this.skipStart);
     }
-    reverse() {
-        switch (this.direction) {
-            case IteratorDirection.Ascending:
-                this.direction = IteratorDirection.Descending;
-                return this;
-            case IteratorDirection.Descending:
-                this.direction = IteratorDirection.Ascending;
-                return this;
-        }
-    }
     equals(value) {
         if (this.isPrimary) {
             const item = this.table.get(value);

package/dist/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/table.d.ts

@@ -15,61 +15,182 @@ export type TableEvent<A extends object, PK> = {
     type: "delete";
     key: PK;
 };
-export declare class Table<A extends object, PI extends UnitIndex<A>, Ix extends object> extends Emitter<TableEvent<A, PI["keyType"]>> implements Disposable, Iterable<Readonly<A>> {
+/**
+ * A database table.
+ *
+ * To learn how to create a table, see the static method {@link Table.create}.
+ *
+ * @template Document The type of the documents this table stores.
+ */
+export declare class Table<Document extends object, PrimaryIndex extends UnitIndex<Document>, Indices extends object> extends Emitter<TableEvent<Document, PrimaryIndex["keyType"]>> implements Disposable, Iterable<Readonly<Document>> {
     #private;
-    ready: Promise<void>;
-    readonly primaryIndex: PI;
-    readonly primary: BTree<PI["keyType"], Readonly<A>>;
+    /**
+     * A promise which resolves when this table is ready to use.
+     *
+     * If the table isn't connected to a {@link StorageBackend}, this is a
+     * promise which resolves immediately, and you don't really need to await
+     * it. The table will be ready for use immediately.
+     *
+     * With an attached {@link StorageBackend}, this promise will resolve when
+     * the table has finished restoring its contents from the storage. You
+     * should not under any circumstances use the table before this is complete.
+     */
+    get ready(): Promise<void>;
+    /** @ignore */
+    readonly primaryIndex: PrimaryIndex;
+    /** @ignore */
+    readonly primary: BTree<PrimaryIndex["keyType"], Readonly<Document>>;
+    /** @ignore */
     readonly indices: {
-        [K in Exclude<keyof Ix & string, PI["name"]>]: Index<A>;
+        [K in Exclude<keyof Indices & string, PrimaryIndex["name"]>]: Index<Document>;
     };
+    /** @ignore */
     readonly indexTables: {
-        [K in Exclude<keyof Ix & string, PI["name"]>]: BTree<Ix[K], Array<A>>;
+        [K in Exclude<keyof Indices & string, PrimaryIndex["name"]>]: BTree<Indices[K], Array<Document>>;
+    };
+    /**
+     * A signal which updates whenever the table has been modified.
+     */
+    get changed(): Signal.Computed<null>;
+    /**
+     * Create a database {@link Table}.
+     *
+     * `Table.create` is a function which takes one type argument, the type of the
+     * object (which we'll call a *document*) you want the table to store, and no
+     * value arguments.
+     *
+     * This returns an object with one method: `withPrimaryIndex`. This method is
+     * what actually creates the table. So, the full incantation is, for instance:
+     *
+     * ```ts
+     * type Document = { id: string; value: number };
+     * const table = Table.create<Document>()
+     *     .withPrimaryIndex(index<Document>().key("id"));
+     * ```
+     *
+     * In order to look up something in a database table, you need an index. You can
+     * create an index using the {@link index} function, which, like `Table.create`,
+     * takes the document you're creating an index for as its type argument, and
+     * returns a selection of index constructors, of which the most straightforward
+     * one is {@link IndexConstructor.key}. This creates an index for a single named
+     * property of the document containing a primitive comparable value (a string, a
+     * number, or a bigint), and allows you to search for documents where the given
+     * property matches any given value. You can also create an index over multiple
+     * keys using {@link IndexConstructor.keys} or over a key containing an array
+     * using {@link IndexConstructor.array}. You can even create a completely
+     * customised index using {@link IndexConstructor.custom}.
+     *
+     * The primary index, unlike a regular index, is a unique identifier, and only
+     * one document can exist at any given time under the key or keys represented by
+     * the primary index. A table is required to have a primary index, which is why
+     * `Table.create` doesn't actually create the table until you call
+     * `withPrimaryIndex` on it. You can then add as many extra indices as you like
+     * using `withIndex`. To extend our example above with an additional index over
+     * the `value` property:
+     *
+     * ```ts
+     * type Document = { id: string; value: number };
+     * const table = Table.create<Document>()
+     *     .withPrimaryIndex(index<Document>().key("id"))
+     *     .withIndex(index<Document>().key("value"));
+     * ```
+     *
+     * @see {@link index}
+     *
+     * @template Document The type of the document this table stores.
+     */
+    static create<Document extends object>(): {
+        withPrimaryIndex: <PrimaryIndex extends UnitIndex<Document>>(primaryIndex: PrimaryIndex) => Table<Document, PrimaryIndex, PrimaryIndex["record"]>;
     };
-    readonly changed: Signal.State<number>;
-    constructor(primaryIndex: PI);
+    /** @internal */
+    private constructor();
     [Symbol.dispose](): void;
-    withIndex<I extends Index<A>>(index: I): Table<A, PI, {
-        [K in keyof (Ix & I["record"])]: (Ix & I["record"])[K];
+    /**
+     * Add an index to a table.
+     *
+     * @example
+     * type Document = { id: string; value: number };
+     * const table = Table.create<Document>()
+     *     .withPrimaryIndex(index<Document>().key("id"))
+     *     .withIndex(index<Document>().key("value"));
+     */
+    withIndex<I extends Index<Document>>(index: I): Table<Document, PrimaryIndex, {
+        [K in keyof (Indices & I["record"])]: (Indices & I["record"])[K];
     }>;
+    /**
+     * Attach a table to a {@link StorageBackend}.
+     *
+     * See {@link IndexedDBBackend.open} for an example of how to use this.
+     */
     withStorage(backend: StorageBackend, name: string): this;
-    signal(primaryKey: PI["keyType"]): Signal.Computed<Readonly<A> | undefined>;
-    get(primaryKey: PI["keyType"]): Readonly<A> | undefined;
+    signal(primaryKey: PrimaryIndex["keyType"]): Signal.Computed<Readonly<Document> | undefined>;
+    get(primaryKey: PrimaryIndex["keyType"]): Readonly<Document> | undefined;
     /**
      * Given a primary key, apply an update function to the value stored under
      * that key. If there's no value, call the create function to create the
      * value before passing it to the update function.
      */
-    createAndUpdate(primaryKey: PI["keyType"], create: () => A, update: (item: Draft<A>) => Draft<A> | void): Readonly<A>;
+    createAndUpdate(primaryKey: PrimaryIndex["keyType"], create: () => Document, update: (item: Draft<Document>) => Draft<Document> | void): Readonly<Document>;
     /**
-     * Given a primary key, apply an update function to the value stored under
-     * that key. If there's no value, call the create function to create a new
-     * value. In this case, the update function is not called.
+     * Create or update a document.
+     *
+     * Given a primary key, apply the `update` function to the document stored
+     * under that key.
+     *
+     * If there's no such document, call the `create` function to create a new
+     * document and insert that under the given primary key. In this case, the
+     * update function is not called.
+     *
+     * The `update` function is passed to {@link produce | Immer.produce} to
+     * perform the update. It should modify the provided document in place, and
+     * it's not necessary to return it.
      */
-    createOrUpdate(primaryKey: PI["keyType"], create: () => A, update: (item: Draft<A>) => Draft<A> | void): Readonly<A>;
+    createOrUpdate(primaryKey: PrimaryIndex["keyType"], create: () => Document, update: (item: Draft<Document>) => Draft<Document> | void): Readonly<Document>;
     /**
-     * Apply an update function to the value stored under the given primary key.
-     * If no value exists, the update function is not called and `undefined` is
-     * returned. Otherwise, the updated value is returned.
+     * Update a document.
+     *
+     * Apply the `update` function to the document stored under the given
+     * primary key.
+     *
+     * If no such document exists, the update function is not called and
+     * `undefined` is returned. Otherwise, the updated document is returned.
+     *
+     * The `update` function is passed to {@link produce | Immer.produce} to
+     * perform the update. It should modify the provided document in place, and
+     * it's not necessary to return it.
      */
-    update(primaryKey: PI["keyType"], update: (item: Draft<A>) => void | Draft<A>): Readonly<A> | undefined;
+    update(primaryKey: PrimaryIndex["keyType"], update: (item: Draft<Document>) => void | Draft<Document>): Readonly<Document> | undefined;
     /**
-     * Add items to the table, overwriting any previous values under their
+     * Add documents to the table, overwriting any previous values under their
      * primary keys.
      */
-    add(...items: Array<A>): void;
-    add(items: Iterable<A>): void;
+    add(...items: Array<Document>): void;
+    add(items: Iterable<Document>): void;
     /**
-     * Delete items from the table by their primary keys.
+     * Delete documents from the table by their primary keys.
      */
-    delete(...primaryKeys: Array<PI["keyType"]>): number;
-    delete(primaryKeys: Iterable<PI["keyType"]>): number;
+    delete(...primaryKeys: Array<PrimaryIndex["keyType"]>): number;
+    delete(primaryKeys: Iterable<PrimaryIndex["keyType"]>): number;
     /**
-     * Delete all data from the table.
+     * Delete all documents from the table.
      */
     clear(): void;
-    [Symbol.iterator](): IterableIterator<Readonly<A>>;
-    where<K extends keyof Ix & string, I extends Index<A> & Ix[K]>(index: K): IndexQuery<A, PI, I, Ix>;
-    orderBy<K extends keyof Ix & string, I extends Index<A> & Ix[K]>(index: K): IndexQuery<A, PI, I, Ix>;
+    /**
+     * Iterate over the documents in the table, ordered by primary key.
+     */
+    [Symbol.iterator](): IteratorObject<Readonly<Document>>;
+    /**
+     * Perform an {@link IndexQuery} using the specified index.
+     */
+    where<K extends keyof Indices & string, I extends Index<Document> & Indices[K]>(index: K): IndexQuery<Document, PrimaryIndex, I, Indices>;
+    /**
+     * Perform an {@link IndexQuery} using the specified index.
+     *
+     * This is an alias for {@link Table.where}.
+     */
+    orderBy<K extends keyof Indices & string, I extends Index<Document> & Indices[K]>(index: K): IndexQuery<Document, PrimaryIndex, I, Indices>;
+    /**
+     * Get the number of documents currently stored in the table.
+     */
     size(): number;
 }

package/dist/table.js

@@ -8,18 +8,105 @@ import BTree from "sorted-btree";
 import { CustomIndex } from "./indices";
 import { IndexQuery, IteratorDirection } from "./query";
 import { TableStorage } from "./storage";
+/**
+ * A database table.
+ *
+ * To learn how to create a table, see the static method {@link Table.create}.
+ *
+ * @template Document The type of the documents this table stores.
+ */
 export class Table extends Emitter {
+    /**
+     * A promise which resolves when this table is ready to use.
+     *
+     * If the table isn't connected to a {@link StorageBackend}, this is a
+     * promise which resolves immediately, and you don't really need to await
+     * it. The table will be ready for use immediately.
+     *
+     * With an attached {@link StorageBackend}, this promise will resolve when
+     * the table has finished restoring its contents from the storage. You
+     * should not under any circumstances use the table before this is complete.
+     */
+    get ready() {
+        return this.#ready;
+    }
+    #ready;
+    #changed;
+    /**
+     * A signal which updates whenever the table has been modified.
+     */
+    get changed() {
+        return this.#changed.readOnly;
+    }
     #storage;
     #signals;
     #signalCleanupRegistry;
     #context;
+    /**
+     * Create a database {@link Table}.
+     *
+     * `Table.create` is a function which takes one type argument, the type of the
+     * object (which we'll call a *document*) you want the table to store, and no
+     * value arguments.
+     *
+     * This returns an object with one method: `withPrimaryIndex`. This method is
+     * what actually creates the table. So, the full incantation is, for instance:
+     *
+     * ```ts
+     * type Document = { id: string; value: number };
+     * const table = Table.create<Document>()
+     *     .withPrimaryIndex(index<Document>().key("id"));
+     * ```
+     *
+     * In order to look up something in a database table, you need an index. You can
+     * create an index using the {@link index} function, which, like `Table.create`,
+     * takes the document you're creating an index for as its type argument, and
+     * returns a selection of index constructors, of which the most straightforward
+     * one is {@link IndexConstructor.key}. This creates an index for a single named
+     * property of the document containing a primitive comparable value (a string, a
+     * number, or a bigint), and allows you to search for documents where the given
+     * property matches any given value. You can also create an index over multiple
+     * keys using {@link IndexConstructor.keys} or over a key containing an array
+     * using {@link IndexConstructor.array}. You can even create a completely
+     * customised index using {@link IndexConstructor.custom}.
+     *
+     * The primary index, unlike a regular index, is a unique identifier, and only
+     * one document can exist at any given time under the key or keys represented by
+     * the primary index. A table is required to have a primary index, which is why
+     * `Table.create` doesn't actually create the table until you call
+     * `withPrimaryIndex` on it. You can then add as many extra indices as you like
+     * using `withIndex`. To extend our example above with an additional index over
+     * the `value` property:
+     *
+     * ```ts
+     * type Document = { id: string; value: number };
+     * const table = Table.create<Document>()
+     *     .withPrimaryIndex(index<Document>().key("id"))
+     *     .withIndex(index<Document>().key("value"));
+     * ```
+     *
+     * @see {@link index}
+     *
+     * @template Document The type of the document this table stores.
+     */
+    static create() {
+        return {
+            withPrimaryIndex(primaryIndex) {
+                return new Table(primaryIndex);
+            },
+        };
+    }
+    /** @internal */
     constructor(primaryIndex) {
         super();
-        this.ready = Promise.resolve();
+        this.#ready = Promise.resolve();
+        /** @ignore */
         this.primary = new BTree();
+        /** @ignore */
         this.indices = {};
+        /** @ignore */
         this.indexTables = {};
-        this.changed = Signal.from(0);
+        this.#changed = Signal.from(null, { equals: () => false });
         this.#signals = new BTree();
         this.#signalCleanupRegistry = new FinalizationRegistry(this.#signalCleanup.bind(this));
         this.#context = new DisposableContext();
@@ -29,6 +116,15 @@ export class Table extends Emitter {
         super[Symbol.dispose]();
         this.#context.dispose();
     }
+    /**
+     * Add an index to a table.
+     *
+     * @example
+     * type Document = { id: string; value: number };
+     * const table = Table.create<Document>()
+     *     .withPrimaryIndex(index<Document>().key("id"))
+     *     .withIndex(index<Document>().key("value"));
+     */
     withIndex(index) {
         assert(this.indices[index.name] === undefined, `duplicate index definition: "${index.name}"`);
         this.indices[index.name] = index;
@@ -36,9 +132,14 @@ export class Table extends Emitter {
             index instanceof CustomIndex ? index.makeIndex() : new BTree();
         return this;
     }
+    /**
+     * Attach a table to a {@link StorageBackend}.
+     *
+     * See {@link IndexedDBBackend.open} for an example of how to use this.
+     */
     withStorage(backend, name) {
         this.#storage = new TableStorage(backend, name, this.primaryIndex);
-        this.ready = this.#storage.ready;
+        this.#ready = this.#storage.ready;
         this.#context.use(this.#storage.on((event) => {
             switch (event.type) {
                 case "update":
@@ -78,9 +179,18 @@ export class Table extends Emitter {
         return this.#setItem(item, oldItem, primaryKey);
     }
     /**
-     * Given a primary key, apply an update function to the value stored under
-     * that key. If there's no value, call the create function to create a new
-     * value. In this case, the update function is not called.
+     * Create or update a document.
+     *
+     * Given a primary key, apply the `update` function to the document stored
+     * under that key.
+     *
+     * If there's no such document, call the `create` function to create a new
+     * document and insert that under the given primary key. In this case, the
+     * update function is not called.
+     *
+     * The `update` function is passed to {@link produce | Immer.produce} to
+     * perform the update. It should modify the provided document in place, and
+     * it's not necessary to return it.
      */
     createOrUpdate(primaryKey, create, update) {
         const oldItem = this.primary.get(primaryKey);
@@ -88,9 +198,17 @@ export class Table extends Emitter {
         return this.#setItem(item, oldItem, primaryKey);
     }
     /**
-     * Apply an update function to the value stored under the given primary key.
-     * If no value exists, the update function is not called and `undefined` is
-     * returned. Otherwise, the updated value is returned.
+     * Update a document.
+     *
+     * Apply the `update` function to the document stored under the given
+     * primary key.
+     *
+     * If no such document exists, the update function is not called and
+     * `undefined` is returned. Otherwise, the updated document is returned.
+     *
+     * The `update` function is passed to {@link produce | Immer.produce} to
+     * perform the update. It should modify the provided document in place, and
+     * it's not necessary to return it.
      */
     update(primaryKey, update) {
         const oldItem = this.primary.get(primaryKey);
@@ -107,20 +225,34 @@ export class Table extends Emitter {
         return this.#deleteFrom(items.length === 1 && isIterable(items[0]) ? items[0] : items);
     }
     /**
-     * Delete all data from the table.
+     * Delete all documents from the table.
      */
     clear() {
         this.delete(...this.primary.keys());
     }
+    /**
+     * Iterate over the documents in the table, ordered by primary key.
+     */
     [Symbol.iterator]() {
-        return this.primary.values();
+        return Iterator.from(this.primary.values());
     }
+    /**
+     * Perform an {@link IndexQuery} using the specified index.
+     */
     where(index) {
         return new IndexQuery(this, index, IteratorDirection.Ascending);
     }
+    /**
+     * Perform an {@link IndexQuery} using the specified index.
+     *
+     * This is an alias for {@link Table.where}.
+     */
     orderBy(index) {
         return this.where(index);
     }
+    /**
+     * Get the number of documents currently stored in the table.
+     */
     size() {
         return this.primary.size;
     }
@@ -176,7 +308,7 @@ export class Table extends Emitter {
         // emit an update event and update signals
         this.#withSignal(this.primaryIndex.extractKey(item), (sig) => sig.set(item));
         this.emit({ type: "update", item });
-        this.changed.update((i) => i + 1);
+        this.#changed.set(null);
         return item;
     }
     #deleteItem(item, primaryKey) {
@@ -187,7 +319,7 @@ export class Table extends Emitter {
         // emit a delete event and update signals
         this.#withSignal(primaryKey, (sig) => sig.set(undefined));
         this.emit({ type: "delete", key: primaryKey });
-        this.changed.update((i) => i + 1);
+        this.#changed.set(null);
     }
     #withSignal(primaryKey, fn) {
         const sigRef = this.#signals.get(primaryKey);