@primate/core 0.4.5 → 0.5.0

package/lib/private/orm/Store.js

@@ -0,0 +1,518 @@
+import E from "#db/error";
+import wrap from "#db/symbol/wrap";
+import parse from "#orm/parse";
+import assert from "@rcompat/assert";
+import is from "@rcompat/is";
+import StoreType from "pema/StoreType";
+const NUMBER_KEYS = [
+    "u8", "u16", "u32",
+    "i8", "i16", "i32",
+    "f32", "f64"
+];
+const BIGINT_KEYS = ["u64", "u128", "i64", "i128"];
+const is_number_key = (d) => NUMBER_KEYS.includes(d);
+const is_bigint_key = (d) => BIGINT_KEYS.includes(d);
+const VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function guard_options(options, allowed) {
+    if (options === undefined)
+        return;
+    const allowed_set = new Set(allowed);
+    for (const k of Object.keys(options)) {
+        if (!allowed_set.has(k))
+            throw E.option_unknown(k);
+    }
+}
+const INT_LIMITS = {
+    u8: [0, 255],
+    u16: [0, 65535],
+    u32: [0, 4294967295],
+    i8: [-128, 127],
+    i16: [-32768, 32767],
+    i32: [-2147483648, 2147483647],
+};
+const BIGINT_LIMITS = {
+    u64: [0n, (1n << 64n) - 1n],
+    i64: [-(1n << 63n), (1n << 63n) - 1n],
+    u128: [0n, (1n << 128n) - 1n],
+    i128: [-(1n << 127n), (1n << 127n) - 1n],
+};
+function assert_number_value(key, datatype, value) {
+    if (!is.finite(value))
+        throw E.where_invalid_value(key, value);
+    if (datatype in INT_LIMITS) {
+        if (!is.safeint(value))
+            throw E.where_invalid_value(key, value);
+        const [min, max] = INT_LIMITS[datatype];
+        if (value < min || value > max)
+            throw E.where_invalid_value(key, value);
+    }
+}
+function assert_bigint_value(key, datatype, value) {
+    const [min, max] = BIGINT_LIMITS[datatype];
+    if (value < min || value > max)
+        throw E.where_invalid_value(key, value);
+}
+const registry = new Map();
+const STRING_OPS = ["$like", "$ilike"];
+const NUMBER_OPS = ["$gt", "$gte", "$lt", "$lte", "$ne"];
+const BIGINT_OPS = ["$gt", "$gte", "$lt", "$lte", "$ne"];
+const DATE_OPS = ["$before", "$after", "$ne"];
+/**
+ * Database-backed store.
+ *
+ * A `Store` 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 Store {
+    #schema;
+    #type;
+    #types;
+    #nullables;
+    #db;
+    #name;
+    #pk;
+    #generate_pk;
+    #fks;
+    #relations;
+    constructor(input, config = {}) {
+        const { pk, generate_pk, fks, schema } = parse(input);
+        this.#schema = schema;
+        this.#type = new StoreType(schema, pk);
+        this.#types = Object.fromEntries(Object.entries(schema).map(([key, value]) => [key, value.datatype]));
+        this.#name = config.name;
+        this.#db = config.db;
+        this.#pk = pk;
+        this.#generate_pk = generate_pk;
+        this.#fks = fks;
+        this.#relations = config.relations ?? {};
+        this.#nullables = new Set(Object.entries(this.#type.properties)
+            .filter(([, v]) => v.nullable)
+            .map(([k]) => k));
+        registry.set(input, this);
+    }
+    static new(input, config = {}) {
+        return new Store(input, config);
+    }
+    get #as() {
+        return {
+            table: this.name,
+            pk: this.#pk,
+            generate_pk: this.#generate_pk,
+            types: this.#types,
+        };
+    }
+    get collection() {
+        const db = this.db;
+        const name = this.name;
+        const schema = this.#schema;
+        const as = this.#as;
+        return {
+            create: () => db.schema.create(as, schema),
+            delete: () => db.schema.delete(name),
+        };
+    }
+    get infer() {
+        return undefined;
+    }
+    get schema() {
+        return this.#schema;
+    }
+    get type() {
+        return this.#type;
+    }
+    [wrap](name, db) {
+        this.#db ??= db;
+        this.#name ??= name;
+        return this;
+    }
+    get db() {
+        if (this.#db === undefined)
+            throw E.db_missing();
+        return this.#db;
+    }
+    get types() {
+        return this.#types;
+    }
+    get name() {
+        const name = this.#name;
+        if (name === undefined)
+            throw E.store_name_required();
+        if (!VALID_IDENTIFIER.test(name))
+            throw E.identifier_invalid(name);
+        return name;
+    }
+    #parse_query(query, types) {
+        const { where, select, sort, limit } = query;
+        if (where !== undefined)
+            this.#parse_where(where, types);
+        if (select !== undefined)
+            this.#parse_select(select, types);
+        if (sort !== undefined)
+            this.#parse_sort(sort, types);
+        if (limit !== undefined && !is.uint(limit))
+            throw E.limit_invalid();
+    }
+    #with(options) {
+        if (options === undefined)
+            return undefined;
+        const plan = {};
+        for (const [name, query] of Object.entries(options)) {
+            if (query === undefined)
+                continue;
+            const relation = this.#relations[name];
+            if (relation === undefined)
+                throw E.relation_unknown(name);
+            const store = registry.get(relation.schema);
+            if (store === undefined)
+                throw E.unregistered_schema();
+            const { pk: target_pk } = parse(relation.schema);
+            const target_types = store.types;
+            const base = {
+                as: {
+                    table: store.name,
+                    pk: target_pk,
+                    types: target_types,
+                },
+                kind: relation.type,
+                fk: relation.fk,
+                reverse: "reverse" in relation && relation.reverse === true,
+            };
+            if (query === true) {
+                plan[name] = { ...base, where: {} };
+                continue;
+            }
+            this.#parse_query(query, target_types);
+            plan[name] = {
+                ...base,
+                where: query.where ?? {},
+                fields: query.select ? [...query.select] : undefined,
+                sort: query.sort,
+                limit: query.limit,
+            };
+        }
+        return plan;
+    }
+    #parse_where(where, types) {
+        if (!is.dict(where))
+            throw E.where_invalid();
+        for (const [k, value] of Object.entries(where)) {
+            if (!VALID_IDENTIFIER.test(k))
+                throw E.identifier_invalid(k);
+            if (!(k in types))
+                throw E.field_unknown(k, "where");
+            if (value === undefined)
+                throw E.field_undefined(k, "where");
+            const datatype = types[k];
+            // null criteria (IS NULL semantics)
+            if (value === null)
+                continue;
+            // arrays are always invalid
+            if (is.array(value))
+                throw E.where_invalid_value(k, value);
+            if (is.dict(value)) {
+                const ops = Object.entries(value);
+                if (ops.length === 0)
+                    throw E.operator_empty(k);
+                for (const [op, op_val] of ops) {
+                    if (op_val === undefined)
+                        throw E.field_undefined(k, "where");
+                    if (datatype === "string" || datatype === "time") {
+                        if (!STRING_OPS.includes(op))
+                            throw E.operator_unknown(k, op);
+                        if (!is.string(op_val))
+                            throw E.wrong_type("string", k, op_val, op);
+                        continue;
+                    }
+                    if (is_number_key(datatype)) {
+                        if (!NUMBER_OPS.includes(op))
+                            throw E.operator_unknown(k, op);
+                        if (!is.number(op_val))
+                            throw E.wrong_type("number", k, op_val, op);
+                        assert_number_value(k, datatype, op_val);
+                        continue;
+                    }
+                    if (is_bigint_key(datatype)) {
+                        if (!BIGINT_OPS.includes(op))
+                            throw E.operator_unknown(k, op);
+                        if (!is.bigint(op_val))
+                            throw E.wrong_type("bigint", k, op_val, op);
+                        assert_bigint_value(k, datatype, op_val);
+                        continue;
+                    }
+                    if (datatype === "datetime") {
+                        if (!DATE_OPS.includes(op))
+                            throw E.operator_unknown(k, op);
+                        if (!is.date(op_val))
+                            throw E.wrong_type("date", k, op_val, op);
+                        continue;
+                    }
+                    // url/boolean/blob: no operator objects
+                    throw E.operator_unknown(k, op);
+                }
+                continue;
+            }
+            switch (datatype) {
+                case "string":
+                case "time":
+                    if (!is.string(value))
+                        throw E.wrong_type("string", k, value);
+                    continue;
+                case "u8":
+                case "u16":
+                case "u32":
+                case "i8":
+                case "i16":
+                case "i32":
+                case "f32":
+                case "f64":
+                    if (!is.number(value))
+                        throw E.wrong_type("number", k, value);
+                    assert_number_value(k, datatype, value);
+                    continue;
+                case "u64":
+                case "u128":
+                case "i64":
+                case "i128":
+                    if (!is.bigint(value))
+                        throw E.wrong_type("bigint", k, value);
+                    assert_bigint_value(k, datatype, value);
+                    continue;
+                case "datetime":
+                    if (!is.date(value))
+                        throw E.wrong_type("date", k, value);
+                    continue;
+                case "boolean":
+                    if (!is.boolean(value))
+                        throw E.wrong_type("boolean", k, value);
+                    continue;
+                case "url":
+                    if (!is.url(value))
+                        throw E.wrong_type("url", k, value);
+                    continue;
+                case "blob":
+                    if (!is.blob(value))
+                        throw E.wrong_type("blob", k, value);
+                    continue;
+                default:
+                    throw E.where_invalid_value(k, value);
+            }
+        }
+    }
+    #parse_select(select, types) {
+        if (!is.array(select))
+            throw E.select_invalid();
+        if (select.length === 0)
+            throw E.select_empty();
+        const seen = new Set();
+        for (const [i, v] of select.entries()) {
+            if (!is.string(v))
+                throw E.select_invalid_value(i, v);
+            if (!VALID_IDENTIFIER.test(v))
+                throw E.identifier_invalid(v);
+            if (!(v in types))
+                throw E.field_unknown(v, "select");
+            // duplicate isn't harmful, but usually a thought error
+            if (seen.has(v))
+                throw E.field_duplicate(v, "select");
+            seen.add(v);
+        }
+    }
+    #parse_sort(sort, types) {
+        if (!is.dict(sort))
+            throw E.sort_invalid();
+        const keys = Object.keys(sort);
+        if (keys.length === 0)
+            throw E.sort_empty();
+        for (const [k, direction] of Object.entries(sort)) {
+            if (!is.string(direction))
+                throw E.sort_invalid_value(k, direction);
+            if (!(k in types))
+                throw E.field_unknown(k, "sort");
+            const l = direction.toLowerCase();
+            if (l !== "asc" && l !== "desc")
+                throw E.sort_invalid_value(k, direction);
+        }
+    }
+    #parse_insert(record) {
+        for (const [k, v] of Object.entries(record)) {
+            if (!(k in this.#types))
+                throw E.field_unknown(k, "insert");
+            if (v === undefined)
+                throw E.field_undefined(k, "insert");
+            if (v === null)
+                throw E.null_not_allowed(k);
+        }
+    }
+    /**
+     * Count records
+     */
+    async count(options) {
+        this.#parse_query(options ?? {}, this.#types);
+        if (is.defined(options) && "with" in options)
+            throw E.count_with_invalid();
+        return await this.db.read(this.#as, {
+            count: true,
+            where: (options?.where ?? {}),
+        });
+    }
+    /**
+     * Check whether a record with the given primary key exists.
+     */
+    async has(pkv) {
+        if (this.#pk === null)
+            throw E.pk_undefined(this.name);
+        return (await this.count({ where: { [this.#pk]: pkv } })) === 1;
+    }
+    async get(pkv, options) {
+        const pk = this.#pk;
+        if (pk === null)
+            throw E.pk_undefined(this.name);
+        guard_options(options, ["select", "with"]);
+        this.#parse_query(options ?? {}, this.#types);
+        const $with = this.#with(options?.with);
+        const records = await this.db.read(this.#as, {
+            where: { [pk]: pkv },
+            fields: options?.select ? [...options.select] : undefined,
+            with: $with,
+        });
+        assert.true(records.length <= 1);
+        if (records.length === 0) {
+            const err = E.record_not_found(pk, pkv);
+            err.not_found = true;
+            throw err;
+        }
+        const raw = records[0];
+        // if projected, keep it as-is (no parse)
+        if (options?.select)
+            return raw;
+        // parse *only* base fields (exclude relation keys)
+        const base_only = Object.fromEntries(Object.entries(raw)
+            .filter(([k]) => k in this.#types));
+        const parsed = this.#type.parse(base_only);
+        if ($with === undefined)
+            return parsed;
+        return {
+            ...parsed,
+            ...Object.fromEntries(Object.keys($with).map(k => [k, raw[k]])),
+        };
+    }
+    async try(pkv, options) {
+        try {
+            return await this.get(pkv, options);
+        }
+        catch (error) {
+            if (error?.not_found === true)
+                return undefined;
+            throw error;
+        }
+    }
+    /**
+     * Insert a single record.
+     */
+    async insert(record) {
+        assert.dict(record);
+        this.#parse_insert(record);
+        const entries = Object.entries(record);
+        const to_parse = Object.fromEntries(entries.filter(([k, v]) => !(v === null && this.#nullables.has(k))));
+        return this.db.create(this.#as, this.#type.parse(to_parse));
+    }
+    async update(arg0, options) {
+        const by_pk = options !== undefined;
+        const set = by_pk
+            ? options.set
+            : arg0.set;
+        if (!is.dict(set) || is.empty(set))
+            throw E.set_empty();
+        const pk = this.#pk;
+        if (pk !== null && pk in set)
+            throw E.pk_immutable(pk);
+        for (const [k, v] of Object.entries(set)) {
+            if (!(k in this.#types))
+                throw E.field_unknown(k, "set");
+            if (v === null && !this.#nullables.has(k))
+                throw E.null_not_allowed(k);
+        }
+        const entries = Object.entries(set);
+        const to_parse = Object.fromEntries(entries
+            .filter(([key, value]) => value !== null || !this.#nullables.has(key)));
+        const nulls = Object.fromEntries(entries
+            .filter(([key, value]) => value === null && this.#nullables.has(key)));
+        const parsed = {
+            ...this.#type.partial().parse(to_parse),
+            ...nulls,
+        };
+        if (by_pk) {
+            return this.#update_1(arg0, parsed);
+        }
+        const where = arg0.where;
+        if (where !== undefined)
+            this.#parse_where(where, this.#types);
+        return this.#update_n((where ?? {}), parsed);
+    }
+    async #update_1(pkv, set) {
+        const pk = this.#pk;
+        if (pk === null)
+            throw E.pk_undefined(this.name);
+        const n = await this.db.update(this.#as, {
+            set: set,
+            where: { [pk]: pkv },
+        });
+        assert.true(n === 1, `${n} records updated instead of 1`);
+    }
+    async #update_n(where, set) {
+        return await this.db.update(this.#as, {
+            set: set,
+            where: where,
+        });
+    }
+    async delete(pkv_or_options) {
+        if (is.dict(pkv_or_options)) {
+            const where = pkv_or_options.where;
+            if (!is.dict(where) || is.empty(where))
+                throw E.where_required();
+            this.#parse_where(where, this.#types);
+            return this.#delete_n(where);
+        }
+        return this.#delete_1(pkv_or_options);
+    }
+    async #delete_1(pkv) {
+        const pk = this.#pk;
+        if (pk === null)
+            throw E.pk_undefined(this.name);
+        const n = await this.db.delete(this.#as, { where: { [pk]: pkv } });
+        assert.true(n === 1, `${n} records deleted instead of 1`);
+    }
+    async #delete_n(where) {
+        return await this.db.delete(this.#as, { where: where });
+    }
+    /**
+     * Find matching records
+     *
+     */
+    async find(options) {
+        guard_options(options, ["where", "select", "sort", "limit", "with"]);
+        this.#parse_query(options ?? {}, this.#types);
+        const result = await this.db.read(this.#as, {
+            where: options?.where ?? {},
+            fields: options?.select ? [...options.select] : undefined,
+            limit: options?.limit,
+            sort: options?.sort,
+            with: this.#with(options?.with),
+        });
+        return result;
+    }
+    toJSON() {
+        return this.#type.toJSON();
+    }
+    extend(extensor) {
+        const extensions = extensor(this);
+        const keys = Object.keys(extensions);
+        for (const k of keys)
+            if (k in this)
+                throw E.key_duplicate(k);
+        Object.assign(this, extensions);
+        return this;
+    }
+}
+//# sourceMappingURL=Store.js.map

package/lib/private/orm/foreign.d.ts

@@ -0,0 +1,4 @@
+import ForeignKey from "#orm/ForeignKey";
+import type { DataKey, Storable } from "pema";
+export default function foreign<T extends Storable<DataKey>>(type: T): ForeignKey<T>;
+//# sourceMappingURL=foreign.d.ts.map

package/lib/private/orm/foreign.js

@@ -0,0 +1,5 @@
+import ForeignKey from "#orm/ForeignKey";
+export default function foreign(type) {
+    return new ForeignKey(type);
+}
+//# sourceMappingURL=foreign.js.map

package/lib/private/orm/key.d.ts

@@ -0,0 +1,8 @@
+import foreign from "#orm/foreign";
+import primary from "#orm/primary";
+declare const _default: {
+    primary: typeof primary;
+    foreign: typeof foreign;
+};
+export default _default;
+//# sourceMappingURL=key.d.ts.map

package/lib/private/orm/key.js

@@ -0,0 +1,4 @@
+import foreign from "#orm/foreign";
+import primary from "#orm/primary";
+export default { primary, foreign };
+//# sourceMappingURL=key.js.map

package/lib/private/orm/parse.d.ts

@@ -0,0 +1,12 @@
+import ForeignKey from "#orm/ForeignKey";
+import type { StoreInput } from "#orm/types";
+import type { Dict } from "@rcompat/type";
+import type { Storable } from "pema";
+import type PK from "#db/PK";
+export default function parse(input: StoreInput): {
+    pk: PK;
+    generate_pk: boolean;
+    fks: Map<string, ForeignKey<Storable<keyof import("pema").DataType>>>;
+    schema: Dict<Storable<keyof import("pema").DataType>>;
+};
+//# sourceMappingURL=parse.d.ts.map

package/lib/private/orm/parse.js

@@ -0,0 +1,29 @@
+import fail from "#fail";
+import ForeignKey from "#orm/ForeignKey";
+import PrimaryKey from "#orm/PrimaryKey";
+const is_pk = (x) => x instanceof PrimaryKey;
+const is_fk = (x) => x instanceof ForeignKey;
+export default function parse(input) {
+    let pk = null;
+    let generate_pk = true;
+    const fks = new Map();
+    const schema = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (is_pk(value)) {
+            if (pk !== null)
+                throw fail("multiple primary keys: {0}, {1}", pk, key);
+            pk = key;
+            generate_pk = value.generate;
+            schema[key] = value.type;
+        }
+        else if (is_fk(value)) {
+            fks.set(key, value);
+            schema[key] = value.type;
+        }
+        else {
+            schema[key] = value;
+        }
+    }
+    return { pk, generate_pk, fks, schema };
+}
+//# sourceMappingURL=parse.js.map

package/lib/private/orm/primary.d.ts

@@ -0,0 +1,5 @@
+import type { Options } from "#orm/PrimaryKey";
+import PrimaryKey from "#orm/PrimaryKey";
+import type { DataKey, Storable } from "pema";
+export default function primary<T extends Storable<DataKey>>(type: T, options?: Options): PrimaryKey<T>;
+//# sourceMappingURL=primary.d.ts.map

package/lib/private/orm/primary.js

@@ -0,0 +1,5 @@
+import PrimaryKey from "#orm/PrimaryKey";
+export default function primary(type, options) {
+    return new PrimaryKey(type, options);
+}
+//# sourceMappingURL=primary.js.map

package/lib/private/orm/relation.d.ts

@@ -0,0 +1,43 @@
+import type Store from "#orm/Store";
+import type { StoreInput } from "#orm/types";
+/**
+ * extracts schema type from either a schema or a Store.
+ */
+type SchemaOf<T> = T extends Store<infer S, any> ? S : T;
+/**
+ * One relation (singular) - returns single record or null
+ *
+ * Normal: FK is on the OTHER table, pointing to this table's PK.
+ *   Author has one Profile -> Profile has author_id
+ *
+ * Reverse: FK is on THIS table, pointing to other table's PK.
+ *   Profile belongs to Author -> Profile has author_id
+ */
+export type OneRelation<T extends StoreInput, FK extends string> = {
+    type: "one";
+    schema: T;
+    fk: FK;
+    reverse: boolean;
+};
+/**
+ * Many relation (plural) - returns array of records
+ *
+ * FK is always on the OTHER table, pointing to this table's PK.
+ *   Example: Author has many Articles → Article has author_id
+ */
+export type ManyRelation<T extends StoreInput, FK extends string> = {
+    type: "many";
+    schema: T;
+    fk: FK;
+};
+export type Relation = OneRelation<any, string> | ManyRelation<any, string>;
+declare function one<T extends StoreInput | Store<StoreInput, any>, FK extends string>(input: T, fk: FK, options?: {
+    reverse?: boolean;
+}): OneRelation<SchemaOf<T>, FK>;
+declare function many<T extends StoreInput | Store<StoreInput, any>, FK extends string>(input: T, fk: FK): ManyRelation<SchemaOf<T>, FK>;
+declare const _default: {
+    one: typeof one;
+    many: typeof many;
+};
+export default _default;
+//# sourceMappingURL=relation.d.ts.map

package/lib/private/orm/relation.js

@@ -0,0 +1,26 @@
+import is from "@rcompat/is";
+function is_store(value) {
+    return is.dict(value) && "schema" in value && is.function(value.get);
+}
+function extract_schema(schema_or_store) {
+    return (is_store(schema_or_store)
+        ? schema_or_store.schema
+        : schema_or_store);
+}
+function one(input, fk, options) {
+    return {
+        type: "one",
+        schema: extract_schema(input),
+        fk,
+        reverse: options?.reverse ?? false,
+    };
+}
+function many(input, fk) {
+    return {
+        type: "many",
+        schema: extract_schema(input),
+        fk,
+    };
+}
+export default { one, many };
+//# sourceMappingURL=relation.js.map

package/lib/private/orm/types.d.ts

@@ -0,0 +1,18 @@
+import type ForeignKey from "#orm/ForeignKey";
+import type PrimaryKey from "#orm/PrimaryKey";
+import type { ManyRelation, OneRelation } from "#orm/relation";
+import type { Dict } from "@rcompat/type";
+import type { DataKey, InferStore, Storable } from "pema";
+type Relation = OneRelation<any, string> | ManyRelation<any, string>;
+type StoreField = Storable<DataKey> | PrimaryKey<Storable<DataKey>> | ForeignKey<Storable<DataKey>>;
+type StoreInput = Dict<StoreField>;
+type PrimaryKeyField<T extends StoreInput> = {
+    [K in keyof T]: T[K] extends PrimaryKey<any> ? K : never;
+}[keyof T] & keyof InferRecord<T>;
+type ExtractSchema<T extends StoreInput> = {
+    [K in keyof T]: T[K] extends PrimaryKey<infer P> ? P : T[K] extends ForeignKey<infer P> ? P : T[K] extends Storable<DataKey> ? T[K] : never;
+};
+type InferRecord<T extends StoreInput> = InferStore<ExtractSchema<T>>;
+type Insertable<T extends StoreInput> = Omit<InferRecord<T>, PrimaryKeyField<T>> & Partial<Pick<InferRecord<T>, PrimaryKeyField<T>>>;
+export type { ExtractSchema, InferRecord, Insertable, PrimaryKeyField, Relation, StoreField, StoreInput, };
+//# sourceMappingURL=types.d.ts.map