@bodil/bdb 0.1.2 → 0.2.0

package/src/table.ts

@@ -17,27 +17,130 @@ export type TableEvent<A extends object, PK> =
     | { type: "update"; item: A }
     | { type: "delete"; key: PK };
 
-export 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 class Table<
+    Document extends object,
+    PrimaryIndex extends UnitIndex<Document>,
+    Indices extends object,
+>
+    extends Emitter<TableEvent<Document, PrimaryIndex["keyType"]>>
+    implements Disposable, Iterable<Readonly<Document>>
 {
-    ready: Promise<void> = Promise.resolve();
-
-    readonly primaryIndex: PI;
-    readonly primary = new BTree<PI["keyType"], Readonly<A>>();
-    readonly indices: { [K in Exclude<keyof Ix & string, PI["name"]>]: Index<A> } = {} as any;
+    /**
+     * 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> {
+        return this.#ready;
+    }
+    #ready: Promise<void> = Promise.resolve();
+
+    /** @ignore */
+    readonly primaryIndex: PrimaryIndex;
+    /** @ignore */
+    readonly primary = new BTree<PrimaryIndex["keyType"], Readonly<Document>>();
+    /** @ignore */
+    readonly indices: {
+        [K in Exclude<keyof Indices & string, PrimaryIndex["name"]>]: Index<Document>;
+    } = {} as any;
+    /** @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>
+        >;
     } = {} as any;
 
-    readonly changed = Signal.from(0);
+    readonly #changed = Signal.from(null, { equals: () => false });
+    /**
+     * A signal which updates whenever the table has been modified.
+     */
+    get changed(): Signal.Computed<null> {
+        return this.#changed.readOnly;
+    }
 
-    #storage?: TableStorage<A, PI>;
-    readonly #signals = new BTree<PI["keyType"], WeakRef<Signal.State<Readonly<A> | undefined>>>();
+    #storage?: TableStorage<Document, PrimaryIndex>;
+    readonly #signals = new BTree<
+        PrimaryIndex["keyType"],
+        WeakRef<Signal.State<Readonly<Document> | undefined>>
+    >();
     readonly #signalCleanupRegistry = new FinalizationRegistry(this.#signalCleanup.bind(this));
     readonly #context = new DisposableContext();
 
-    constructor(primaryIndex: PI) {
+    /**
+     * 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"]>;
+    } {
+        return {
+            withPrimaryIndex(primaryIndex) {
+                return new Table(primaryIndex);
+            },
+        };
+    }
+
+    /** @internal */
+    private constructor(primaryIndex: PrimaryIndex) {
         super();
         this.primaryIndex = primaryIndex;
     }
@@ -47,9 +150,22 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         this.#context.dispose();
     }
 
-    withIndex<I extends Index<A>>(
+    /**
+     * 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<A, PI, { [K in keyof (Ix & I["record"])]: (Ix & I["record"])[K] }> {
+    ): Table<
+        Document,
+        PrimaryIndex,
+        { [K in keyof (Indices & I["record"])]: (Indices & I["record"])[K] }
+    > {
         assert(
             (this.indices as any)[index.name] === undefined,
             `duplicate index definition: "${index.name}"`,
@@ -57,14 +173,23 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         (this.indices as any)[index.name] = index;
         (this.indexTables as any)[index.name] =
             index instanceof CustomIndex ? index.makeIndex() : new BTree();
-        return this as Table<A, PI, { [K in keyof (Ix & I["record"])]: (Ix & I["record"])[K] }>;
+        return this as 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 {
         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: TableEvent<A, PI["keyType"]>) => {
+            this.#storage.on((event: TableEvent<Document, PrimaryIndex["keyType"]>) => {
                 switch (event.type) {
                     case "update":
                         this.add(event.item);
@@ -79,20 +204,20 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         return this;
     }
 
-    signal(primaryKey: PI["keyType"]): Signal.Computed<Readonly<A> | undefined> {
+    signal(primaryKey: PrimaryIndex["keyType"]): Signal.Computed<Readonly<Document> | undefined> {
         const active = this.#signals.get(primaryKey)?.deref();
         if (active !== undefined) {
-            return active.readOnly();
+            return active.readOnly;
         }
         const sig = Signal.from(this.get(primaryKey), {
             equals: () => false,
         });
         this.#signalCleanupRegistry.register(sig, primaryKey);
         this.#signals.set(primaryKey, new WeakRef(sig));
-        return sig.readOnly();
+        return sig.readOnly;
     }
 
-    get(primaryKey: PI["keyType"]): Readonly<A> | undefined {
+    get(primaryKey: PrimaryIndex["keyType"]): Readonly<Document> | undefined {
         return this.primary.get(primaryKey);
     }
 
@@ -102,39 +227,56 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
      * value before passing it to the update function.
      */
     createAndUpdate(
-        primaryKey: PI["keyType"],
-        create: () => A,
-        update: (item: Draft<A>) => Draft<A> | void,
-    ): Readonly<A> {
+        primaryKey: PrimaryIndex["keyType"],
+        create: () => Document,
+        update: (item: Draft<Document>) => Draft<Document> | void,
+    ): Readonly<Document> {
         const oldItem = this.primary.get(primaryKey) ?? create();
         const item = produce(oldItem, update);
         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: PI["keyType"],
-        create: () => A,
-        update: (item: Draft<A>) => Draft<A> | void,
-    ): Readonly<A> {
+        primaryKey: PrimaryIndex["keyType"],
+        create: () => Document,
+        update: (item: Draft<Document>) => Draft<Document> | void,
+    ): Readonly<Document> {
         const oldItem = this.primary.get(primaryKey);
         const item = oldItem === undefined ? create() : produce(oldItem, update);
         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: PI["keyType"],
-        update: (item: Draft<A>) => void | Draft<A>,
-    ): Readonly<A> | undefined {
+        primaryKey: PrimaryIndex["keyType"],
+        update: (item: Draft<Document>) => void | Draft<Document>,
+    ): Readonly<Document> | undefined {
         const oldItem = this.primary.get(primaryKey);
         if (oldItem === undefined) {
             return undefined;
@@ -144,63 +286,77 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
     }
 
     /**
-     * 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<A | Iterable<A>>) {
+    add(...items: Array<Document>): void;
+    add(items: Iterable<Document>): void;
+    add(...items: Array<Document | Iterable<Document>>) {
         return this.#addFrom(
-            items.length === 1 && isIterable(items[0]) ? items[0] : (items as Array<A>),
+            items.length === 1 && isIterable(items[0]) ? items[0] : (items as Array<Document>),
         );
     }
 
     /**
-     * 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(...items: Array<PI["keyType"] | Iterable<PI["keyType"]>>): number {
+    delete(...primaryKeys: Array<PrimaryIndex["keyType"]>): number;
+    delete(primaryKeys: Iterable<PrimaryIndex["keyType"]>): number;
+    delete(...items: Array<PrimaryIndex["keyType"] | Iterable<PrimaryIndex["keyType"]>>): number {
         return this.#deleteFrom(
-            items.length === 1 && isIterable(items[0]) ? items[0] : (items as Array<A>),
+            items.length === 1 && isIterable(items[0]) ? items[0] : (items as Array<Document>),
         );
     }
 
     /**
-     * Delete all data from the table.
+     * Delete all documents from the table.
      */
     clear() {
         this.delete(...this.primary.keys());
     }
 
-    [Symbol.iterator](): IterableIterator<Readonly<A>> {
-        return this.primary.values();
+    /**
+     * Iterate over the documents in the table, ordered by primary key.
+     */
+    [Symbol.iterator](): IteratorObject<Readonly<Document>> {
+        return Iterator.from(this.primary.values());
     }
 
-    where<K extends keyof Ix & string, I extends Index<A> & Ix[K]>(
+    /**
+     * Perform an {@link IndexQuery} using the specified index.
+     */
+    where<K extends keyof Indices & string, I extends Index<Document> & Indices[K]>(
         index: K,
-    ): IndexQuery<A, PI, I, Ix> {
+    ): IndexQuery<Document, PrimaryIndex, I, Indices> {
         return new IndexQuery(this, index, IteratorDirection.Ascending);
     }
 
-    orderBy<K extends keyof Ix & string, I extends Index<A> & Ix[K]>(
+    /**
+     * 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<A, PI, I, Ix> {
+    ): IndexQuery<Document, PrimaryIndex, I, Indices> {
         return this.where(index);
     }
 
+    /**
+     * Get the number of documents currently stored in the table.
+     */
     size(): number {
         return this.primary.size;
     }
 
-    #addFrom(items: Iterable<A>) {
+    #addFrom(items: Iterable<Document>) {
         for (const item of items) {
             const key = this.primaryIndex.extractKey(item);
             this.#setItem(item, this.primary.get(key), key);
         }
     }
 
-    #deleteFrom(primaryKeys: Iterable<PI["keyType"]>): number {
+    #deleteFrom(primaryKeys: Iterable<PrimaryIndex["keyType"]>): number {
         let deleted = 0;
         for (const primaryKey of primaryKeys) {
             const item = this.primary.get(primaryKey);
@@ -212,7 +368,11 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         return deleted;
     }
 
-    #setItem(item: A, oldItem: Readonly<A> | undefined, key: PI["keyType"]): A {
+    #setItem(
+        item: Document,
+        oldItem: Readonly<Document> | undefined,
+        key: PrimaryIndex["keyType"],
+    ): Document {
         freeze(item, true);
 
         // make sure the primary key matches the value
@@ -252,11 +412,11 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         // 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: A, primaryKey: PI["keyType"]) {
+    #deleteItem(item: Document, primaryKey: PrimaryIndex["keyType"]) {
         // remove the item from indices
         this.#deleteFromIndices(item);
         // remove the item from the primary index
@@ -264,12 +424,12 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         // 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: PI["keyType"],
-        fn: (signal: Signal.State<Readonly<A> | undefined>) => void,
+        primaryKey: PrimaryIndex["keyType"],
+        fn: (signal: Signal.State<Readonly<Document> | undefined>) => void,
     ) {
         const sigRef = this.#signals.get(primaryKey);
         const sig = sigRef?.deref();
@@ -282,7 +442,7 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         }
     }
 
-    #deleteFromIndices(item: A) {
+    #deleteFromIndices(item: Document) {
         for (const property of Object.keys(this.indices)) {
             const index = (this.indices as any)[property];
             const table = (this.indexTables as any)[property];
@@ -303,7 +463,7 @@ export class Table<A extends object, PI extends UnitIndex<A>, Ix extends object>
         }
     }
 
-    #signalCleanup(primaryKey: PI["keyType"]) {
+    #signalCleanup(primaryKey: PrimaryIndex["keyType"]) {
         this.#signals.delete(primaryKey);
     }
 }

package/src/types.ts

@@ -1,4 +1,4 @@
-export type IndexablePrimitive = string | number | null | undefined | bigint;
+export type IndexablePrimitive = string | number | bigint;
 export type IndexableType =
     | IndexablePrimitive
     | Array<IndexablePrimitive>