@bodil/bdb 0.1.0

package/src/serial.ts

@@ -0,0 +1,92 @@
+const primitives = new Set(["string", "number", "boolean", "undefined"]);
+
+export type Serialised = { type?: string; value?: unknown } | Array<Serialised>;
+
+export function serialise(value: unknown): Serialised {
+    if (primitives.has(typeof value)) {
+        return { value: value as any };
+    } else if (typeof value === "symbol") {
+        throw new TypeError(`don't know how to serialise a symbol: ${value.toString()}`);
+    } else if (typeof value === "bigint") {
+        return { type: "bigint", value: value.toString() };
+    } else if (value === null) {
+        return { type: "null" };
+    } else if (Array.isArray(value)) {
+        return value.map(serialise);
+    } else if (value instanceof Set) {
+        return { type: "set", value: value.keys().map(serialise).toArray() };
+    } else if (value instanceof Map) {
+        return {
+            type: "map",
+            value: value
+                .entries()
+                .map(([k, v]) => [serialise(k), serialise(v)])
+                .toArray(),
+        };
+    } else if (value instanceof Temporal.Instant) {
+        return { type: "instant", value: value.toJSON() };
+    } else if (value instanceof Temporal.Duration) {
+        return { type: "duration", value: value.toJSON() };
+    } else if (value instanceof Temporal.PlainDate) {
+        return { type: "plaindate", value: value.toJSON() };
+    } else if (value instanceof Temporal.ZonedDateTime) {
+        return { type: "zdt", value: value.toJSON() };
+    } else if (value instanceof Date) {
+        throw new TypeError(
+            "serialise: Date objects are unsupported, please use Temporal.Instant instead",
+        );
+    } else if (typeof value === "object") {
+        return {
+            type: "object",
+            value: Object.entries(value)
+                .filter(([k]) => typeof k !== "symbol")
+                .map(([k, v]) => [k, serialise(v)]),
+        };
+    } else {
+        throw new TypeError(
+            `serialise: don't know how to serialise this ${typeof value}: ${JSON.stringify(value)}`,
+        );
+    }
+}
+
+export function deserialise(record: Serialised): unknown {
+    if (Array.isArray(record)) {
+        return record.map(deserialise);
+    }
+    switch (record.type) {
+        case undefined:
+            return record.value;
+        case "null":
+            return null;
+        case "bigint":
+            return BigInt(record.value as string);
+        case "instant":
+            return Temporal.Instant.from(record.value as string);
+        case "duration":
+            return Temporal.Duration.from(record.value as string);
+        case "plaindate":
+            return Temporal.PlainDate.from(record.value as string);
+        case "zdt":
+            return Temporal.ZonedDateTime.from(record.value as string);
+        case "set":
+            return new Set((record.value as Array<Serialised>).map(deserialise));
+        case "map":
+            return new Map(
+                (record.value as Array<[Serialised, Serialised]>).map(([k, v]) => [
+                    deserialise(k),
+                    deserialise(v),
+                ]),
+            );
+        case "object":
+            return Object.fromEntries(
+                (record.value as Array<[string | number | symbol, Serialised]>).map(([k, v]) => [
+                    k,
+                    deserialise(v),
+                ]),
+            );
+        default:
+            throw new TypeError(
+                `deserialise: can't deserialise type ${JSON.stringify(record.type)} value ${JSON.stringify(record.value)}`,
+            );
+    }
+}

package/src/storage.ts

@@ -0,0 +1,83 @@
+import { isNullish } from "@bodil/core/assert";
+import { Emitter } from "@bodil/core/async";
+import { DisposableContext } from "@bodil/core/disposable";
+
+import type { DatabaseBroadcast, StorageBackend } from "./backend";
+import type { UnitIndex } from "./indices";
+import type { Table, TableEvent } from "./table";
+
+export class TableStorage<A extends object, PI extends UnitIndex<A>>
+    extends Emitter<TableEvent<A, PI["keyType"]>>
+    implements Disposable
+{
+    readonly #ready = Promise.withResolvers<void>();
+    context = new DisposableContext();
+
+    get ready(): Promise<void> {
+        return this.#ready.promise;
+    }
+
+    constructor(
+        public store: StorageBackend,
+        public name: string,
+        public primaryKey: PI,
+    ) {
+        super();
+        this.context.use(this.store.onBroadcast((message) => this.onBroadcastMessage(message)));
+    }
+
+    override [Symbol.dispose]() {
+        super[Symbol.dispose]();
+        this.context.dispose();
+    }
+
+    private onBroadcastMessage(message: DatabaseBroadcast): void {
+        if (message.table !== this.name) {
+            return;
+        }
+        switch (message.event) {
+            case "update":
+                void this.store.get<A>(this.name, message.key).then((row) => {
+                    if (!isNullish(row)) {
+                        this.emit({ type: "update", item: row });
+                    }
+                });
+                break;
+            case "delete":
+                this.emit({ type: "delete", key: message.key });
+                break;
+        }
+    }
+
+    private readonly onTableEvent = (event: TableEvent<A, PI["keyType"]>) => {
+        switch (event.type) {
+            case "update":
+                this.update(event.item);
+                break;
+            case "delete":
+                this.delete(event.key);
+                break;
+        }
+    };
+
+    async link<Ix extends object>(table: Table<A, PI, Ix>) {
+        let rows: Array<A>;
+        try {
+            rows = await this.store.getAll<A>(this.name);
+        } catch (e) {
+            this.#ready.reject(e);
+            return;
+        }
+        table.add(...rows);
+        this.context.use(table.on((event) => this.onTableEvent(event)));
+        this.#ready.resolve();
+    }
+
+    private update(item: A) {
+        void this.store.update(this.name, this.primaryKey.extractKey(item), item);
+    }
+
+    private delete(key: PI["keyType"]) {
+        void this.store.delete(this.name, key);
+    }
+}

package/src/table.ts

@@ -0,0 +1,302 @@
+import { assert, isIterable } from "@bodil/core/assert";
+import { Emitter } from "@bodil/core/async";
+import { DisposableContext } from "@bodil/core/disposable";
+import { Signal } from "@bodil/signal";
+import { freeze, produce, type Draft } from "immer";
+import BTree from "sorted-btree";
+
+import type { StorageBackend } from "./backend";
+import { CustomIndex, type Index, type UnitIndex } from "./indices";
+import { IndexQuery, IteratorDirection } from "./query";
+import { TableStorage } from "./storage";
+
+export type TableObserveOptions = { includeCurrent: boolean };
+
+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>>
+{
+    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;
+    readonly indexTables: {
+        [K in Exclude<keyof Ix & string, PI["name"]>]: BTree<Ix[K], Array<A>>;
+    } = {} as any;
+
+    readonly changed = Signal(0);
+
+    #storage?: TableStorage<A, PI>;
+    readonly #signals = new BTree<PI["keyType"], WeakRef<Signal.State<Readonly<A> | undefined>>>();
+    readonly #signalCleanupRegistry = new FinalizationRegistry(this.#signalCleanup.bind(this));
+    readonly #context = new DisposableContext();
+
+    constructor(primaryIndex: PI) {
+        super();
+        this.primaryIndex = primaryIndex;
+    }
+
+    override [Symbol.dispose]() {
+        super[Symbol.dispose]();
+        this.#context.dispose();
+    }
+
+    withIndex<I extends Index<A>>(
+        index: I,
+    ): Table<A, PI, { [K in keyof (Ix & I["record"])]: (Ix & I["record"])[K] }> {
+        assert(
+            (this.indices as any)[index.name] === undefined,
+            `duplicate index definition: "${index.name}"`,
+        );
+        (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] }>;
+    }
+
+    withStorage(backend: StorageBackend, name: string): this {
+        this.#storage = new TableStorage(backend, name, this.primaryIndex);
+        this.ready = this.#storage.ready;
+        this.#context.use(
+            this.#storage.on((event: TableEvent<A, PI["keyType"]>) => {
+                switch (event.type) {
+                    case "update":
+                        this.add(event.item);
+                        break;
+                    case "delete":
+                        this.delete(event.key);
+                        break;
+                }
+            }),
+        );
+        void this.#storage.link(this);
+        return this;
+    }
+
+    signal(primaryKey: PI["keyType"]): Signal.Computed<Readonly<A> | undefined> {
+        const active = this.#signals.get(primaryKey)?.deref();
+        if (active !== undefined) {
+            return active.readOnly();
+        }
+        const sig = Signal(this.get(primaryKey), {
+            equals: () => false,
+        });
+        this.#signalCleanupRegistry.register(sig, primaryKey);
+        this.#signals.set(primaryKey, new WeakRef(sig));
+        return sig.readOnly();
+    }
+
+    get(primaryKey: PI["keyType"]): Readonly<A> | undefined {
+        return this.primary.get(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 the
+     * value before passing it to the update function.
+     */
+    createAndUpdate(
+        primaryKey: PI["keyType"],
+        create: () => A,
+        update: (item: Draft<A>) => Draft<A> | void,
+    ): Readonly<A> {
+        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.
+     */
+    createOrUpdate(
+        primaryKey: PI["keyType"],
+        create: () => A,
+        update: (item: Draft<A>) => Draft<A> | void,
+    ): Readonly<A> {
+        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(
+        primaryKey: PI["keyType"],
+        update: (item: Draft<A>) => void | Draft<A>,
+    ): Readonly<A> | undefined {
+        const oldItem = this.primary.get(primaryKey);
+        if (oldItem === undefined) {
+            return undefined;
+        }
+        const item = produce(oldItem, update);
+        return this.#setItem(item, oldItem, primaryKey);
+    }
+
+    /**
+     * Add items 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>>) {
+        return this.#addFrom(
+            items.length === 1 && isIterable(items[0]) ? items[0] : (items as Array<A>),
+        );
+    }
+
+    /**
+     * Delete items 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 {
+        return this.#deleteFrom(
+            items.length === 1 && isIterable(items[0]) ? items[0] : (items as Array<A>),
+        );
+    }
+
+    /**
+     * Delete all data from the table.
+     */
+    clear() {
+        this.delete(...this.primary.keys());
+    }
+
+    [Symbol.iterator](): IterableIterator<Readonly<A>> {
+        return this.primary.values();
+    }
+
+    where<K extends keyof Ix & string, I extends Index<A> & Ix[K]>(
+        index: K,
+    ): IndexQuery<A, PI, I, Ix> {
+        return new IndexQuery(this, index, IteratorDirection.Ascending);
+    }
+
+    orderBy<K extends keyof Ix & string, I extends Index<A> & Ix[K]>(
+        index: K,
+    ): IndexQuery<A, PI, I, Ix> {
+        return this.where(index);
+    }
+
+    size(): number {
+        return this.primary.size;
+    }
+
+    #addFrom(items: Iterable<A>) {
+        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 {
+        let deleted = 0;
+        for (const primaryKey of primaryKeys) {
+            const item = this.primary.get(primaryKey);
+            if (item !== undefined) {
+                this.#deleteItem(item, primaryKey);
+                deleted++;
+            }
+        }
+        return deleted;
+    }
+
+    #setItem(item: A, oldItem: Readonly<A> | undefined, key: PI["keyType"]): A {
+        freeze(item, true);
+
+        // stop now if the new value is the same as the old one
+        if (Object.is(oldItem, item)) {
+            return item;
+        }
+
+        // remove the old item from indices
+        if (oldItem !== undefined) {
+            this.#deleteFromIndices(oldItem);
+        }
+
+        // store the new item under its primary key, overwriting the old value
+        this.primary.set(key, item, true);
+
+        // add new item to indices
+        for (const property of Object.keys(this.indices)) {
+            const index = (this.indices as any)[property];
+            const table = (this.indexTables as any)[property];
+            const keys = index.extractKeys(item);
+            for (const key of keys) {
+                const record = table.get(key);
+                if (record === undefined) {
+                    table.set(key, [item]);
+                } else {
+                    record.push(item);
+                }
+            }
+        }
+
+        // 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);
+        return item;
+    }
+
+    #deleteItem(item: A, primaryKey: PI["keyType"]) {
+        // remove the item from indices
+        this.#deleteFromIndices(item);
+        // remove the item from the primary index
+        this.primary.delete(primaryKey);
+        // 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);
+    }
+
+    #withSignal(
+        primaryKey: PI["keyType"],
+        fn: (signal: Signal.State<Readonly<A> | undefined>) => void,
+    ) {
+        const sigRef = this.#signals.get(primaryKey);
+        const sig = sigRef?.deref();
+        if (sig !== undefined) {
+            // Only run the function if we have a live signal
+            return fn(sig);
+        } else if (sigRef !== undefined) {
+            // Remove dangling reference from signal map
+            this.#signals.delete(primaryKey);
+        }
+    }
+
+    #deleteFromIndices(item: A) {
+        for (const property of Object.keys(this.indices)) {
+            const index = (this.indices as any)[property];
+            const table = (this.indexTables as any)[property];
+            const keys = index.extractKeys(item);
+            for (const key of keys) {
+                const record = table.get(key);
+                if (record !== undefined) {
+                    const recordIndex = record.indexOf(item);
+                    if (recordIndex >= 0) {
+                        if (record.length === 1) {
+                            table.delete(key);
+                        } else {
+                            record.splice(recordIndex, 1);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    #signalCleanup(primaryKey: PI["keyType"]) {
+        this.#signals.delete(primaryKey);
+    }
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+export type IndexablePrimitive = string | number | null | undefined | bigint;
+export type IndexableType =
+    | IndexablePrimitive
+    | Array<IndexablePrimitive>
+    | ReadonlyArray<IndexablePrimitive>;
+
+export type CustomIndexablesOf<A, T> = string &
+    keyof A &
+    { [Key in keyof A]: A[Key] extends T ? Key : never }[keyof A];
+
+export type IndexablesOf<A> = CustomIndexablesOf<A, IndexableType>;
+export type PrimitiveIndexablesOf<A> = CustomIndexablesOf<A, IndexablePrimitive>;
+export type ArrayIndexablesOf<A> = CustomIndexablesOf<
+    A,
+    Array<IndexablePrimitive> | ReadonlyArray<IndexablePrimitive>
+>;