@bodil/bdb 0.1.2 → 0.2.0

package/src/index.ts

@@ -1,8 +1,7 @@
 import type { OrderFn } from "@bodil/core/order";
 import BTree from "sorted-btree";
 
-import { ArrayIndex, CompoundIndex, CustomIndex, PrimitiveIndex, type UnitIndex } from "./indices";
-import { Table } from "./table";
+import { ArrayIndex, CompoundIndex, CustomIndex, PrimitiveIndex } from "./indices";
 import type { ArrayIndexablesOf, CustomIndexablesOf, PrimitiveIndexablesOf } from "./types";
 
 export type {
@@ -19,58 +18,126 @@ export type {
     CustomIndexablesOf,
     PrimitiveIndexablesOf,
 } from "./types";
-export type { Table, TableEvent } from "./table";
+export { Table, type TableEvent } from "./table";
 export type { IndexQuery, ArrayQuery, ChainQuery } from "./query";
 export type { Broadcaster } from "./broadcast";
 export type { IndexedDBBackendConfig, DatabaseBroadcast } from "./backend";
 
 export { StorageBackend, IndexedDBBackend } from "./backend";
 
-export function createTable<A extends object>(): <PI extends UnitIndex<A>>(
-    primaryIndex: PI,
-) => Table<A, PI, PI["record"]> {
-    return (primaryIndex) => new Table(primaryIndex);
-}
+/**
+ * Constructor functions for creating an {@link index}.
+ * @interface
+ */
+export type IndexConstructor<Document extends object> = {
+    /**
+     * Create an index for a single property on a document.
+     *
+     * The type of the property needs to match {@link IndexablePrimitive}, ie.
+     * it needs to be a string, a number or a bigint. If you need an index for a
+     * different value type, use {@link IndexConstructor.custom}.
+     *
+     * @example
+     * type Document = { id: string; value: number };
+     * const index = index<Document>().key("id");
+     */
+    key: <I extends PrimitiveIndexablesOf<Document>>(key: I) => PrimitiveIndex<Document, I>;
 
-export function index<A extends object>(): <I extends PrimitiveIndexablesOf<A>>(
-    key: I,
-) => PrimitiveIndex<A, I> {
-    return (key) => new PrimitiveIndex(key);
-}
+    /**
+     * Create a compound index for a pair of properties on a document.
+     *
+     * The types of the properties need to match {@link IndexablePrimitive}, ie.
+     * they need to be strings, numbers or bigints.
+     *
+     * This index matches documents where both properties match the provided
+     * pair of values. Partial matches do not count.
+     *
+     * Whemn a compound index is used as a primary index, the unique key is the
+     * value pair, not either of the individual values, so you can have multiple
+     * documents with either one of the properties having identical values, but
+     * only one document matching any one given value pair.
+     *
+     * @example
+     * type Document = { id: string; value: number };
+     * const compoundIndex = index<Document>().keys("id", "value");
+     */
+    keys: <
+        I extends PrimitiveIndexablesOf<Document>,
+        J extends Exclude<PrimitiveIndexablesOf<Document>, I>,
+    >(
+        leftKey: I,
+        rightKey: J,
+    ) => CompoundIndex<Document, I, J>;
 
-export function timeIndex<A extends object>(): <I extends CustomIndexablesOf<A, Temporal.Instant>>(
-    key: I,
-) => CustomIndex<A, Temporal.Instant, I> {
-    return (key) =>
-        new CustomIndex(
-            key,
-            () => new BTree(undefined, Temporal.Instant.compare as OrderFn<A[typeof key]>),
-        );
-}
+    /**
+     * Create an array index for a property on a document.
+     *
+     * This index works on a property with an array of
+     * {@link IndexablePrimitive}s. It will match documents where the lookup
+     * value is a member of the array.
+     *
+     * @example
+     * type Document = { id: string; flags: Array<string> };
+     * const arrayIndex = index<Document>().array("flags");
+     */
+    array: <I extends ArrayIndexablesOf<Document>, L extends Document[I] & Array<unknown>>(
+        key: I,
+    ) => ArrayIndex<Document, I, L>;
 
-export function arrayIndex<A extends object>(): <
-    I extends ArrayIndexablesOf<A>,
-    L extends A[I] & Array<unknown>,
->(
-    key: I,
-) => ArrayIndex<A, I, L> {
-    return (key) => new ArrayIndex(key);
-}
+    /**
+     * Create an index for a {@link Temporal.Instant} property on a document.
+     *
+     * This works exactly like {@link IndexConstructor.key}, except that it
+     * takes a {@link Temporal.Instant} instead of a primitive value.
+     */
+    time: <I extends CustomIndexablesOf<Document, Temporal.Instant>>(
+        key: I,
+    ) => CustomIndex<Document, Temporal.Instant, I>;
 
-export function compoundIndex<A extends object>(): <
-    I extends PrimitiveIndexablesOf<A>,
-    J extends Exclude<PrimitiveIndexablesOf<A>, I>,
->(
-    leftKey: I,
-    rightKey: J,
-) => CompoundIndex<A, I, J> {
-    return (leftKey, rightKey) => new CompoundIndex(leftKey, rightKey);
-}
+    /**
+     * Create an index with a custom ordering function for a property on a
+     * document.
+     *
+     * This works like {@link IndexConstructor.key}, except that it takes any
+     * value rather than just a primitive, as long as you provide an
+     * {@link OrderFn | ordering function} for it.
+     */
+    custom: <T, I extends CustomIndexablesOf<Document, T>>(
+        key: I,
+        orderFn: OrderFn<T>,
+    ) => CustomIndex<Document, T, I>;
+};
+
+const indexConstructor = Symbol("indexConstructor");
 
-export function customIndex<A extends object, T>(): <I extends CustomIndexablesOf<A, T>>(
-    key: I,
-    orderFn: OrderFn<T>,
-) => CustomIndex<A, T, I> {
-    return (key, orderFn: OrderFn<T>) =>
-        new CustomIndex(key, () => new BTree(undefined, orderFn as OrderFn<A[typeof key]>));
+/**
+ * Create an index.
+ *
+ * This function takes a document type as its type argument, and returns an
+ * object with a selection of {@link IndexConstructor}s which allow you to
+ * create an index for the given document type.
+ *
+ * @example
+ * type Document = { id: string; timestamp: Temporal.Instant };
+ * const idIndex = index<Document>().key("id");
+ * const timeIndex = index<Document>().time("timestamp");
+ */
+export function index<Document extends object>(): IndexConstructor<Document> {
+    (index as any)[indexConstructor] ??= {
+        key: (key) => new PrimitiveIndex(key),
+        keys: (leftKey, rightKey) => new CompoundIndex(leftKey, rightKey),
+        array: (key) => new ArrayIndex(key),
+        time: (key) =>
+            new CustomIndex(
+                key,
+                () =>
+                    new BTree(undefined, Temporal.Instant.compare as OrderFn<Document[typeof key]>),
+            ),
+        custom: (key, orderFn) =>
+            new CustomIndex(
+                key,
+                () => new BTree(undefined, orderFn as OrderFn<Document[typeof key]>),
+            ),
+    } as IndexConstructor<Document>;
+    return (index as any)[indexConstructor] as IndexConstructor<Document>;
 }

package/src/indices.ts

@@ -2,6 +2,7 @@ import type BTree from "sorted-btree";
 
 import type { ArrayIndexablesOf, CustomIndexablesOf, PrimitiveIndexablesOf } from "./types";
 
+/** @internal */
 export abstract class Index<A extends object> {
     readonly name!: string;
     readonly keyType!: unknown;
@@ -9,10 +10,12 @@ export abstract class Index<A extends object> {
     abstract extractKeys(value: A): Array<typeof this.keyType>;
 }
 
+/** @internal */
 export abstract class UnitIndex<A extends object> extends Index<A> {
     abstract extractKey(value: A): typeof this.keyType;
 }
 
+/** @internal */
 export class CustomIndex<A extends object, T, I extends CustomIndexablesOf<A, T>>
     implements Index<A>, UnitIndex<A>
 {
@@ -37,6 +40,7 @@ export class CustomIndex<A extends object, T, I extends CustomIndexablesOf<A, T>
     }
 }
 
+/** @internal */
 export class PrimitiveIndex<A extends object, I extends PrimitiveIndexablesOf<A>>
     implements Index<A>, UnitIndex<A>
 {
@@ -58,12 +62,12 @@ export class PrimitiveIndex<A extends object, I extends PrimitiveIndexablesOf<A>
     }
 }
 
+/** @internal */
 export class ArrayIndex<
     A extends object,
     I extends ArrayIndexablesOf<A>,
     L extends A[I] & Array<unknown>,
-> implements Index<A>
-{
+> implements Index<A> {
     readonly index: I;
     readonly name: `*${I}`;
     readonly keyType!: L[number];
@@ -79,11 +83,12 @@ export class ArrayIndex<
     }
 }
 
+/** @internal */
 export class CompoundIndex<
-        A extends object,
-        I extends PrimitiveIndexablesOf<A>,
-        J extends Exclude<PrimitiveIndexablesOf<A>, I>,
-    >
+    A extends object,
+    I extends PrimitiveIndexablesOf<A>,
+    J extends Exclude<PrimitiveIndexablesOf<A>, I>,
+>
     implements Index<A>, UnitIndex<A>
 {
     readonly leftIndex: I;

package/src/query.ts

@@ -9,29 +9,25 @@ import type { Table } from "./table";
 export enum IteratorDirection {
     Ascending = 0,
     Descending = 1,
-    DescendingExclusive = 2,
 }
 
-function* indexIterator<A extends object, I extends Index<A>>(
-    table: BTree<I["keyType"], Array<A>>,
+function* indexIterator<Document extends object, I extends Index<Document>>(
+    table: BTree<I["keyType"], Array<Document>>,
     direction: IteratorDirection,
     start?: I["keyType"],
-): Generator<Readonly<A>> {
+    skipStart = false,
+): Generator<Readonly<Document>> {
     if (table.isEmpty) {
         return;
     }
-    if (direction === IteratorDirection.Ascending) {
-        for (const items of table.values(start)) {
-            for (const item of items) {
-                yield item;
-            }
-        }
-    } else {
-        for (const entry of table.entriesReversed(
-            start,
-            undefined,
-            direction === IteratorDirection.DescendingExclusive,
-        )) {
+    const entries =
+        direction === IteratorDirection.Ascending
+            ? table.entries(start)
+            : table.entriesReversed(start);
+    for (const entry of entries) {
+        if (skipStart && table._compare(entry[0], start) === 0) {
+            skipStart = false;
+        } else {
             for (const item of entry[1]) {
                 yield item;
             }
@@ -39,94 +35,100 @@ function* indexIterator<A extends object, I extends Index<A>>(
     }
 }
 
-function* primaryIndexIterator<A extends object, I extends UnitIndex<A>>(
-    table: BTree<I["keyType"], Readonly<A>>,
+function* primaryIndexIterator<Document extends object, I extends UnitIndex<Document>>(
+    table: BTree<I["keyType"], Readonly<Document>>,
     direction: IteratorDirection,
     start?: I["keyType"],
-): Generator<Readonly<A>> {
+    skipStart = false,
+): Generator<Readonly<Document>> {
     if (table.isEmpty) {
         return;
     }
-    if (direction === IteratorDirection.Ascending) {
-        for (const item of table.values(start)) {
-            yield item;
-        }
-    } else {
-        for (const entry of table.entriesReversed(
-            start,
-            undefined,
-            direction === IteratorDirection.DescendingExclusive,
-        )) {
+    const entries =
+        direction === IteratorDirection.Ascending
+            ? table.entries(start)
+            : table.entriesReversed(start);
+    for (const entry of entries) {
+        if (skipStart && table._compare(entry[0], start) === 0) {
+            skipStart = false;
+        } else {
             yield entry[1];
         }
     }
 }
 
-export abstract class Query<A extends object> implements Iterable<Readonly<A>> {
-    abstract [Symbol.iterator](): IterableIterator<Readonly<A>>;
-    abstract signal(): Signal.Computed<Array<Readonly<A>>>;
+export 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<A>) => B): IterableIterator<B> {
+    map<B>(mapFn: (item: Readonly<Document>) => B): IterableIterator<B> {
         return Iterator.from(this).map(mapFn);
     }
 
-    forEach(action: (item: A) => void): void {
+    forEach(action: (item: Document) => void): void {
         for (const item of this) {
             action(item);
         }
     }
 
-    toArray(): Array<Readonly<A>> {
+    toArray(): Array<Readonly<Document>> {
         return Array.from(this);
     }
 }
 
 export abstract class TableQuery<
-    A extends object,
-    PI extends UnitIndex<A>,
+    Document extends object,
+    PI extends UnitIndex<Document>,
     Ix extends object,
-> extends Query<A> {
-    table: Table<A, PI, Ix>;
+> extends Query<Document> {
+    /** @ignore */
+    protected table: Table<Document, PI, Ix>;
 
-    constructor(table: Table<A, PI, Ix>) {
+    constructor(table: Table<Document, PI, Ix>) {
         super();
         this.table = table;
     }
 
-    signal(): Signal.Computed<Array<Readonly<A>>> {
+    signal(): Signal.Computed<Array<Readonly<Document>>> {
         return Signal.computed(() => {
             this.table.changed.get();
             return Array.from(this);
         });
     }
 
+    /**
+     * Delete all documents from the table matching this query.
+     */
     delete(): number {
-        return this.table.delete(...Array.from(this));
+        return this.table.delete(
+            ...Array.from(this).map((doc) => this.table.primaryIndex.extractKey(doc)),
+        );
     }
 
-    filter(predicate: (item: Readonly<A>) => boolean): ChainQuery<A, PI, Ix> {
+    filter(predicate: (item: Readonly<Document>) => boolean): ChainQuery<Document, PI, Ix> {
         return new ChainQuery(this.table, this, (iter) => Iterator.from(iter).filter(predicate));
     }
 
-    limit(count: number): ChainQuery<A, PI, Ix> {
+    limit(count: number): ChainQuery<Document, PI, Ix> {
         return new ChainQuery(this.table, this, (iter) => Iterator.from(iter).take(count));
     }
 }
 
 export class IndexQuery<
-    A extends object,
-    PI extends UnitIndex<A>,
-    I extends Index<A>,
+    Document extends object,
+    PI extends UnitIndex<Document>,
+    I extends Index<Document>,
     Ix extends object,
-> extends TableQuery<A, PI, Ix> {
+> extends TableQuery<Document, PI, Ix> {
     private readonly index: I;
-    private readonly indexTable?: BTree<I["keyType"], Array<A>>;
+    private readonly indexTable?: BTree<I["keyType"], Array<Document>>;
     private readonly isPrimary: boolean;
     private start?: I["keyType"];
+    private skipStart = false;
     private direction: IteratorDirection;
 
     constructor(
-        table: Table<A, PI, Ix>,
+        table: Table<Document, PI, Ix>,
         indexKey: keyof Ix & string,
         direction: IteratorDirection,
         start?: I["keyType"],
@@ -144,10 +146,10 @@ export class IndexQuery<
         this.start = start;
     }
 
-    [Symbol.iterator](): IterableIterator<Readonly<A>> {
+    [Symbol.iterator](): IterableIterator<Readonly<Document>> {
         return this.isPrimary
-            ? primaryIndexIterator(this.table.primary, this.direction, this.start)
-            : indexIterator(this.indexTable!, this.direction, this.start);
+            ? primaryIndexIterator(this.table.primary, this.direction, this.start, this.skipStart)
+            : indexIterator(this.indexTable!, this.direction, this.start, this.skipStart);
     }
 
     reverse(): this {
@@ -158,12 +160,10 @@ export class IndexQuery<
             case IteratorDirection.Descending:
                 this.direction = IteratorDirection.Ascending;
                 return this;
-            case IteratorDirection.DescendingExclusive:
-                throw new Error("not sure how to reverse IteratorDirection.DescendingExclusive");
         }
     }
 
-    equals(value: I["keyType"]): ArrayQuery<A, PI, Ix> {
+    equals(value: I["keyType"]): ArrayQuery<Document, PI, Ix> {
         if (this.isPrimary) {
             const item = this.table.get(value);
             return new ArrayQuery(this.table, item === undefined ? [] : [item]);
@@ -173,7 +173,20 @@ export class IndexQuery<
 
     below(value: I["keyType"]): this {
         this.start = value;
-        this.direction = IteratorDirection.DescendingExclusive;
+        this.direction = IteratorDirection.Descending;
+        this.skipStart = true;
+        return this;
+    }
+
+    above(value: I["keyType"]): this {
+        this.start = value;
+        this.direction = IteratorDirection.Ascending;
+        this.skipStart = true;
+        return this;
+    }
+
+    inclusive(): this {
+        this.skipStart = false;
         return this;
     }
 
@@ -191,43 +204,45 @@ export class IndexQuery<
 }
 
 export class ChainQuery<
-    A extends object,
-    PI extends UnitIndex<A>,
+    Document extends object,
+    PI extends UnitIndex<Document>,
     Ix extends object,
-> extends TableQuery<A, PI, Ix> {
-    private readonly parent: Query<A>;
+> extends TableQuery<Document, PI, Ix> {
+    private readonly parent: Query<Document>;
     private readonly iterator: (
-        parentIterator: IterableIterator<Readonly<A>>,
-    ) => IterableIterator<Readonly<A>>;
+        parentIterator: IterableIterator<Readonly<Document>>,
+    ) => IterableIterator<Readonly<Document>>;
 
     constructor(
-        table: Table<A, PI, Ix>,
-        parent: Query<A>,
-        iterator: (parentIterator: IterableIterator<Readonly<A>>) => IterableIterator<Readonly<A>>,
+        table: Table<Document, PI, Ix>,
+        parent: Query<Document>,
+        iterator: (
+            parentIterator: IterableIterator<Readonly<Document>>,
+        ) => IterableIterator<Readonly<Document>>,
     ) {
         super(table);
         this.parent = parent;
         this.iterator = iterator;
     }
 
-    [Symbol.iterator](): IterableIterator<Readonly<A>> {
+    [Symbol.iterator](): IterableIterator<Readonly<Document>> {
         return this.iterator(this.parent[Symbol.iterator]());
     }
 }
 
 export class ArrayQuery<
-    A extends object,
-    PI extends UnitIndex<A>,
+    Document extends object,
+    PI extends UnitIndex<Document>,
     Ix extends object,
-> extends TableQuery<A, PI, Ix> {
-    private readonly values: Array<Readonly<A>>;
+> extends TableQuery<Document, PI, Ix> {
+    private readonly values: Array<Readonly<Document>>;
 
-    constructor(table: Table<A, PI, Ix>, values: Array<Readonly<A>>) {
+    constructor(table: Table<Document, PI, Ix>, values: Array<Readonly<Document>>) {
         super(table);
         this.values = values;
     }
 
-    [Symbol.iterator](): IterableIterator<Readonly<A>> {
+    [Symbol.iterator](): IterableIterator<Readonly<Document>> {
         return this.values[Symbol.iterator]();
     }
 }