@primate/core 0.1.9 → 0.2.0

package/lib/private/database/Database.d.ts

@@ -0,0 +1,56 @@
+import type As from "#database/As";
+import type Binds from "#database/Binds";
+import type DataDict from "#database/DataDict";
+import type DataKey from "#database/DataKey";
+import type Sort from "#database/Sort";
+import type TypeMap from "#database/TypeMap";
+import type Types from "#database/Types";
+import type Dict from "@rcompat/type/Dict";
+import type MaybePromise from "@rcompat/type/MaybePromise";
+import type StoreSchema from "pema/StoreSchema";
+export default abstract class Database {
+    #private;
+    abstract close(): MaybePromise<void>;
+    constructor(bindPrefix?: string);
+    ident(name: string): string;
+    table(as: As): string;
+    toSelect(types: Types, columns?: string[]): string;
+    toSort(types: Types, sort?: Sort): string;
+    toLimit(limit?: number): string;
+    toWhere(types: Types, criteria: DataDict): string;
+    toSet(types: Types, changes: DataDict): Promise<{
+        set: string;
+        binds: Binds;
+    }>;
+    column(key: DataKey): string;
+    abstract get typemap(): TypeMap;
+    abstract schema: {
+        create(name: string, description: StoreSchema): MaybePromise<void>;
+        delete(name: string): MaybePromise<void>;
+    };
+    formatBinds(binds: Binds): Binds;
+    bind<In extends DataDict>(types: Types, object: In): Promise<Binds>;
+    bindCriteria(types: Types, criteria: DataDict): Promise<Binds>;
+    unbind(types: Types, object: Dict): Dict;
+    abstract create<O extends Dict>(as: As, args: {
+        record: Dict;
+    }): MaybePromise<O>;
+    abstract read(as: As, args: {
+        count: true;
+        criteria: Dict;
+    }): MaybePromise<number>;
+    abstract read(as: As, args: {
+        criteria: Dict;
+        fields?: string[];
+        limit?: number;
+        sort?: Sort;
+    }): MaybePromise<Dict[]>;
+    abstract update(as: As, args: {
+        changes: Dict;
+        criteria: Dict;
+    }): MaybePromise<number>;
+    abstract delete(as: As, args: {
+        criteria: Dict;
+    }): MaybePromise<number>;
+}
+//# sourceMappingURL=Database.d.ts.map

package/lib/private/database/Database.js

@@ -0,0 +1,153 @@
+import fail from "#fail";
+import maybe from "@rcompat/assert/maybe";
+import entries from "@rcompat/record/entries";
+function required(operation) {
+    fail("{0}: at least one column required", operation);
+}
+function normalizeSort(direction) {
+    if (typeof direction !== "string")
+        throw fail("invalid sort direction {0}", direction);
+    const lowered = direction.toLowerCase();
+    if (lowered !== "asc" && lowered !== "desc")
+        throw fail("invalid sort direction {0}", direction);
+    return lowered.toUpperCase();
+}
+export default class Database {
+    #bindPrefix;
+    constructor(bindPrefix) {
+        this.#bindPrefix = bindPrefix ?? "";
+    }
+    #assert(types, columns) {
+        const known = new Set(Object.keys(types));
+        const unknown = columns.filter(c => !known.has(c));
+        if (unknown.length > 0) {
+            throw fail("unknown column(s) {0}", unknown.join(", "));
+        }
+    }
+    #quote(name) {
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+            throw fail("invalid identifier {0}", name);
+        }
+        return `\`${name}\``;
+    }
+    ident(name) {
+        return this.#quote(name);
+    }
+    table(as) {
+        return this.#quote(as.name);
+    }
+    toSelect(types, columns) {
+        maybe(columns).array();
+        if (!columns)
+            return "*";
+        if (columns.length === 0)
+            throw required("select");
+        this.#assert(types, columns);
+        return columns.map(this.#quote).join(", ");
+    }
+    toSort(types, sort) {
+        maybe(sort).record();
+        if (!sort)
+            return "";
+        const columns = Object.entries(sort);
+        if (columns.length === 0)
+            throw required("sort");
+        this.#assert(types, columns.map(([k]) => k));
+        const order = columns
+            .map(([k, direction]) => `${this.#quote(k)} ${normalizeSort(direction)}`)
+            .join(", ");
+        return ` ORDER BY ${order}`;
+    }
+    toLimit(limit) {
+        maybe(limit).usize();
+        return limit !== undefined ? ` LIMIT ${limit}` : "";
+    }
+    toWhere(types, criteria) {
+        const columns = Object.keys(criteria);
+        this.#assert(types, columns);
+        if (columns.length === 0)
+            return "";
+        const p = this.#bindPrefix; // "$" or ":"
+        const parts = columns.map(column => {
+            const value = criteria[column];
+            // null criteria
+            if (value === null)
+                return `${this.#quote(column)} IS NULL`;
+            if (typeof value === "object") {
+                if ("$like" in value) {
+                    return `${this.#quote(column)} LIKE ${p}${column}`;
+                }
+                //if ("$gte" in value) return `${this.#quote(column)} >= ${p}${column}`;
+                throw fail("unsupported operator in field {0}", column);
+            }
+            return `${this.#quote(column)}=${p}${column}`;
+        });
+        return `WHERE ${parts.join(" AND ")}`;
+    }
+    async toSet(types, changes) {
+        const columns = Object.keys(changes);
+        this.#assert(types, columns);
+        if (columns.length === 0)
+            throw required("set");
+        const p = this.#bindPrefix; // "$" or ":"
+        const set = `SET ${columns.map(c => `${this.#quote(c)}=${p}s_${c}`).join(", ")}`;
+        const raw = Object.fromEntries(columns.map(c => [`s_${c}`, changes[c]]));
+        // bind original keys (e.g. { age: 35 } -> { $age: 35 })
+        const binds = await this.bind(types, raw);
+        return { set, binds };
+    }
+    #bind(key, value) {
+        return value === null
+            ? null
+            : this.typemap[key].bind(value);
+    }
+    #unbind(key, value) {
+        return this.typemap[key].unbind(value);
+    }
+    column(key) {
+        return this.typemap[key].column;
+    }
+    ;
+    // identity
+    formatBinds(binds) {
+        return binds;
+    }
+    async bind(types, object) {
+        const out = Object.fromEntries(await Promise.all(Object.entries(object).map(async ([key, value]) => {
+            // support "s_" pseudo-namespace for SET params
+            const base = key.startsWith("s_") ? key.slice(2) : key;
+            const bound = await this.#bind(types[base], value);
+            return [`${this.#bindPrefix}${key}`, bound];
+        })));
+        return this.formatBinds(out);
+    }
+    async bindCriteria(types, criteria) {
+        const filtered = {};
+        for (const [key, value] of Object.entries(criteria)) {
+            // null isn't bound
+            if (value === null)
+                continue;
+            if (typeof value === "object") {
+                // extract primitive value from operator object
+                if ("$like" in value) {
+                    if (typeof value.$like !== "string") {
+                        throw fail("$like operator requires string value, got {0}", typeof value.$like);
+                    }
+                    filtered[key] = value.$like;
+                }
+            }
+            else {
+                filtered[key] = value;
+            }
+        }
+        return this.bind(types, filtered);
+    }
+    unbind(types, object) {
+        return entries(object)
+            .filter(([, value]) => value !== null)
+            .map(([key, value]) => [key, this.#unbind(types[key], value)])
+            .get();
+    }
+}
+;
+//# sourceMappingURL=Database.js.map

package/lib/private/database/InMemoryDatabase.d.ts

@@ -0,0 +1,37 @@
+import type As from "#database/As";
+import Database from "#database/Database";
+import type DataDict from "#database/DataDict";
+import type Sort from "#database/Sort";
+import type TypeMap from "#database/TypeMap";
+import type Dict from "@rcompat/type/Dict";
+import type MaybePromise from "@rcompat/type/MaybePromise";
+export default class InMemoryDatabase extends Database {
+    #private;
+    get typemap(): TypeMap<Dict>;
+    get schema(): {
+        create: (name: string) => void;
+        delete: (name: string) => void;
+    };
+    close(): void;
+    create<O extends Dict>(as: As, args: {
+        record: Dict;
+    }): MaybePromise<O>;
+    read(as: As, args: {
+        count: true;
+        criteria: DataDict;
+    }): number;
+    read(as: As, args: {
+        criteria: DataDict;
+        fields?: string[];
+        limit?: number;
+        sort?: Sort;
+    }): Dict[];
+    update(as: As, args: {
+        changes: DataDict;
+        criteria: DataDict;
+    }): Promise<number>;
+    delete(as: As, args: {
+        criteria: DataDict;
+    }): number;
+}
+//# sourceMappingURL=InMemoryDatabase.d.ts.map

package/lib/private/database/InMemoryDatabase.js

@@ -0,0 +1,181 @@
+import Database from "#database/Database";
+import fail from "#fail";
+import assert from "@rcompat/assert";
+import entries from "@rcompat/record/entries";
+function match(record, criteria) {
+    return Object.entries(criteria).every(([k, v]) => {
+        const value = record[k];
+        // null criteria (IS NULL semantics)
+        if (v === null)
+            return !Object.hasOwn(record, k);
+        // handle operator objects
+        if (typeof v === "object") {
+            // $like operator
+            if ("$like" in v) {
+                // NULL values don't match LIKE patterns
+                if (value === null || value === undefined)
+                    return false;
+                const $like = v.$like;
+                if (typeof $like !== "string")
+                    throw fail("$like operator requires string, got {0}", typeof $like);
+                const regex = new RegExp("^" + $like.replace(/%/g, ".*").replace(/\?/g, ".") + "$");
+                return regex.test(String(value));
+            }
+            // future: number operators
+            // if ("$gte" in v) return recordValue >= v.$gte;
+            // if ("$gt" in v) return recordValue > v.$gt;
+            // if ("$lte" in v) return recordValue <= v.$lte;
+            // if ("$lt" in v) return recordValue < v.$lt;
+            return false; // unknown operator
+        }
+        // direct equality match
+        return value === v;
+    });
+}
+function filter(record, fields) {
+    return Object.fromEntries(Object.entries(record)
+        .filter(([key]) => fields.includes(key)));
+}
+function toSorted(d1, d2, sort) {
+    return [...entries(sort).valmap(([, value]) => value === "asc" ? 1 : -1)]
+        .reduce((sorting, [field, direction]) => {
+        const left = d1[field];
+        const right = d2[field];
+        // if sorting has been established, it stays fixed
+        if (sorting !== 0) {
+            return sorting;
+        }
+        // equal, sorting doesn't change
+        if (left === right) {
+            return sorting;
+        }
+        if (left < right) {
+            return -1 * direction;
+        }
+        return direction;
+    }, 0);
+}
+function ident(column) {
+    return {
+        bind: value => value,
+        column,
+        unbind: value => value,
+    };
+}
+const typemap = {
+    blob: ident("BLOB"),
+    boolean: ident("BOOLEAN"),
+    datetime: ident("DATE"),
+    f32: ident("NUMBER"),
+    f64: ident("NUMBER"),
+    i128: ident("BIGINT"),
+    i16: ident("NUMBER"),
+    i32: ident("NUMBER"),
+    i64: ident("BIGINT"),
+    i8: ident("NUMBER"),
+    primary: ident("STRING"),
+    string: ident("STRING"),
+    time: ident("STRING"),
+    u128: ident("BIGINT"),
+    u16: ident("NUMBER"),
+    u32: ident("NUMBER"),
+    u64: ident("BIGINT"),
+    u8: ident("NUMBER"),
+    url: ident("URL"),
+};
+export default class InMemoryDatabase extends Database {
+    #collections = {};
+    get typemap() {
+        return typemap;
+    }
+    #new(name) {
+        if (this.#collections[name] !== undefined) {
+            throw fail("collection {0} already exists", name);
+        }
+        this.#collections[name] = [];
+    }
+    #drop(name) {
+        if (this.#collections[name] === undefined) {
+            // do nothing
+        }
+        delete this.#collections[name];
+    }
+    #use(name) {
+        if (this.#collections[name] === undefined) {
+            this.#collections[name] = [];
+        }
+        return this.#collections[name];
+    }
+    get schema() {
+        return {
+            create: this.#new.bind(this),
+            delete: this.#drop.bind(this),
+        };
+    }
+    // noop
+    close() { }
+    create(as, args) {
+        const collection = this.#use(as.name);
+        const record = { ...args.record };
+        if (record.id === undefined) {
+            record.id = crypto.randomUUID();
+        }
+        ;
+        if (typeof record.id !== "string") {
+            throw fail("id must be string, got {0}", record.id);
+        }
+        if (collection.find(stored => stored.id === record.id)) {
+            throw fail("id {0} already exists in the database", record.id);
+        }
+        collection.push({ ...record });
+        return record;
+    }
+    read(as, args) {
+        this.toWhere(as.types, args.criteria);
+        if (args.fields !== undefined)
+            this.toSelect(as.types, args.fields);
+        if (args.sort !== undefined)
+            this.toSort(as.types, args.sort);
+        const collection = this.#use(as.name);
+        const matches = collection.filter(r => match(r, args.criteria));
+        if (args.count === true) {
+            return matches.length;
+        }
+        const sort = args.sort ?? {};
+        const sorted = Object.keys(sort).length === 0
+            ? matches
+            : matches.toSorted((a, b) => toSorted(a, b, sort));
+        const limit = args.limit ?? sorted.length;
+        const fields = args.fields ?? [];
+        return (fields.length === 0
+            ? sorted
+            : sorted.map(s => filter(s, fields))).slice(0, limit);
+    }
+    async update(as, args) {
+        assert(Object.keys(args.criteria).length > 0, "update: no criteria");
+        this.toWhere(as.types, args.criteria);
+        await this.toSet(as.types, args.changes);
+        const collection = this.#use(as.name);
+        const matched = collection.filter(record => match(record, args.criteria));
+        return matched.map(record => {
+            const changed = entries({ ...record, ...args.changes })
+                .filter(([, value]) => value !== null)
+                .get();
+            const index = collection.findIndex(stored => stored.id === record.id);
+            collection.splice(index, 1, changed);
+            return changed;
+        }).length;
+    }
+    delete(as, args) {
+        if (Object.keys(args.criteria).length === 0) {
+            throw fail("delete: no criteria");
+        }
+        this.toWhere(as.types, args.criteria);
+        const collection = this.#use(as.name);
+        const size_before = collection.length;
+        this.#collections[as.name] = collection
+            .filter(record => !match(record, args.criteria));
+        return size_before - this.#use(as.name).length;
+    }
+}
+//# sourceMappingURL=InMemoryDatabase.js.map

package/lib/private/database/Query.d.ts

@@ -0,0 +1,14 @@
+import type StoreSchema from "pema/StoreSchema";
+import type DataRecord from "#database/DataRecord";
+type X<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Filter<T, P extends keyof T> = X<Pick<T, Extract<P, keyof T>>>;
+export default class Query<T extends StoreSchema, P extends keyof DataRecord<T> = keyof DataRecord<T>> {
+    #private;
+    constructor(schema: T);
+    select<K extends P>(...projection: K[]): Query<T, K>;
+    run(): Promise<Filter<DataRecord<T>, P>>;
+}
+export {};
+//# sourceMappingURL=Query.d.ts.map

package/lib/private/database/Query.js

@@ -0,0 +1,15 @@
+export default class Query {
+    #schema;
+    #projection;
+    constructor(schema) {
+        this.#schema = schema;
+    }
+    select(...projection) {
+        this.#projection = projection;
+        return this;
+    }
+    async run() {
+        return this.#schema.infer;
+    }
+}
+//# sourceMappingURL=Query.js.map

package/lib/private/database/QueryBuilder.d.ts

@@ -0,0 +1,14 @@
+import type DataRecord from "#database/DataRecord";
+import type InferStoreOut from "pema/InferStoreOut";
+import type StoreSchema from "pema/StoreSchema";
+type X<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Filter<T, P extends keyof T> = X<Pick<T, Extract<P, keyof T>>>;
+export default abstract class QueryBuilder<T extends StoreSchema, P extends keyof DataRecord<T> = keyof DataRecord<T>> {
+    abstract where(criteria: any): QueryBuilder<T>;
+    abstract select<K extends P>(...fields: K[]): QueryBuilder<T, K>;
+    abstract run(): Promise<Filter<InferStoreOut<T>, P>>;
+}
+export {};
+//# sourceMappingURL=QueryBuilder.d.ts.map

package/lib/private/database/QueryBuilder.js

@@ -0,0 +1,3 @@
+export default class QueryBuilder {
+}
+//# sourceMappingURL=QueryBuilder.js.map

package/lib/private/database/Sort.d.ts

@@ -0,0 +1,4 @@
+import Dict from "@rcompat/type/Dict";
+type Sort = Dict<"asc" | "desc">;
+export type { Sort as default };
+//# sourceMappingURL=Sort.d.ts.map

package/lib/private/database/Sort.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Sort.js.map

package/lib/private/database/Store.d.ts

@@ -0,0 +1,169 @@
+import type Changes from "#database/Changes";
+import type Database from "#database/Database";
+import type DataRecord from "#database/DataRecord";
+import wrap from "#database/symbol/wrap";
+import type Types from "#database/Types";
+import type Dict from "@rcompat/type/Dict";
+import type Serializable from "@rcompat/type/Serializable";
+import type Id from "pema/Id";
+import type InferStore from "pema/InferStore";
+import type StoreId from "pema/StoreId";
+import type StoreSchema from "pema/StoreSchema";
+type X<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type StringOperators = {
+    $like?: string;
+};
+type QueryOperators<T> = T extends string ? T | StringOperators | null : T | null;
+type Criteria<T extends StoreSchema> = X<{
+    [K in keyof Omit<InferStore<T>, "id">]?: QueryOperators<InferStore<T>[K]>;
+} & {
+    id?: StoreId<T> | null;
+}>;
+type Select<T> = {
+    [K in keyof T]?: true;
+};
+type Sort<T> = {
+    [K in keyof T]?: "asc" | "desc";
+};
+type Insertable<T extends StoreSchema> = Omit<InferStore<T>, "id"> & {
+    id?: StoreId<T>;
+};
+type Filter<A, B = undefined> = B extends undefined ? A : {
+    [K in keyof A as K extends keyof B ? B[K] extends true ? K : never : never]: A[K];
+};
+type Config = {
+    database?: Database;
+    name?: string;
+};
+/**
+ * Database-backed store.
+ *
+ * A `DatabaseStore` exposes a typed, validated interface over a relational or
+ * document database table/collection. It pairs a Pema schema with a uniform
+ * CRUD/query API.
+ *
+ */
+export default class DatabaseStore<S extends StoreSchema> implements Serializable {
+    #private;
+    [wrap]: (name: string, database: Database) => this;
+    readonly R: DataRecord<S>;
+    constructor(schema: S, config?: Config);
+    static new<S extends StoreSchema>(schema: S, config?: Config): DatabaseStore<S>;
+    get schema(): {
+        create: () => import("@rcompat/type/MaybePromise").default<void>;
+        delete: () => import("@rcompat/type/MaybePromise").default<void>;
+    };
+    get infer(): InferStore<S>;
+    get database(): Database;
+    get types(): Types;
+    get name(): string;
+    /**
+     * Count records.
+     *
+     * @param criteria Criteria to limit which records are counted.
+     * @returns Number of matching records (or total if no criteria given).
+     */
+    count(criteria?: Criteria<S> | {
+        id: StoreId<S>;
+    }): Promise<number>;
+    /**
+     * Check whether a record with the given id exists.
+     *
+     * @param id Record id.
+     * @returns `true` if a record with the given id exists, otherwise `false`.
+     */
+    has(id: StoreId<S>): Promise<boolean>;
+    /**
+     * Get a record by id.
+     *
+     * @param id Record id.
+     * @throws If no record with the given id exists.
+     * @returns The record for the given id.
+     */
+    get(id: Id): Promise<DataRecord<S>>;
+    /**
+     * Try to get a record by id.
+     *
+     * @param id Record id.
+     * @returns The record if found, otherwise `undefined`.
+     */
+    try(id: Id): Promise<DataRecord<S> | undefined>;
+    /**
+     * Insert a single record.
+     *
+     * If `id` is omitted, the driver generates one. Input is validated
+     * according to the store schema.
+     *
+     * @param record Record to insert (id optional).
+     * @throws If a record with the same id already exists or validation fails.
+     * @returns The inserted record with id.
+     */
+    insert(record: Insertable<S>): Promise<DataRecord<S>>;
+    /**
+     * Update a single record.
+     *
+     * Change semantics:
+     * - missing / undefined -> leave field unchanged
+     * - null -> unset field (only for nullable fields, otherwise throw)
+     * - value -> set field to value
+     *
+     * Change input is validated according to the store schema.
+     *
+     * @param id Record id.
+     * @param changes Partial changes per the rules above.
+     * @throws If the id is missing, `.id` is present in `changes`, attempting to
+     * unset a non-nullable field, validation fails, or no record is updated.
+     */
+    update(id: Id, changes: Changes<S>): Promise<void>;
+    /**
+     * Update multiple records.
+     *
+     * Same change semantics as when updating a single record.
+     *
+     * @param criteria Criteria selecting which records to update.
+     * @param changes Partial changes per the rules above.
+     * @returns Number of updated records (may be 0).
+     */
+    update(criteria: Criteria<S>, changes: Changes<S>): Promise<number>;
+    /**
+     * Delete a single record.
+     *
+     * @param id Record id.
+     * @throws If no records with the given id exists.
+     */
+    delete(id: Id): Promise<void>;
+    /**
+     * Delete multiple records.
+     *
+     * @param criteria Criteria selecting which records to delete.
+     * @returns Number of records deleted (may be 0).
+     */
+    delete(criteria: Criteria<S>): Promise<number>;
+    /**
+     * Find matching records.
+     *
+     * @param criteria Criteria to match records by.
+     * @param options Query options.
+     * @returns Matching records, possibly projected/limited/sorted.
+     */
+    find(criteria: Criteria<S>): Promise<Filter<DataRecord<S>>[]>;
+    find(criteria: Criteria<S>, options: {
+        limit?: number;
+        select?: undefined;
+        sort?: Sort<DataRecord<S>>;
+    }): Promise<Filter<DataRecord<S>>[]>;
+    find<F extends Select<DataRecord<S>>>(criteria: Criteria<S>, options?: {
+        limit?: number;
+        select?: F;
+        sort?: Sort<DataRecord<S>>;
+    }): Promise<Filter<DataRecord<S>, F>[]>;
+    toJSON(): {
+        type: "object";
+        properties: Dict<import("pema/StoreType").Serialized>;
+    };
+    extend<A extends Dict>(extensor: (This: this) => A): this & A;
+}
+export {};
+//# sourceMappingURL=Store.d.ts.map