@primate/core 0.4.6 → 0.6.0

package/lib/private/orm/store.js

@@ -0,0 +1,542 @@
+import E from "#db/errors";
+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 class Store {
+    #schema;
+    #type;
+    #types;
+    #nullables;
+    #name;
+    #db;
+    #pk;
+    #generate_pk;
+    #fks;
+    #relations;
+    #migrate;
+    constructor(init) {
+        const { pk, generate_pk, fks, schema } = parse(init.schema);
+        const { name, db, migrate } = init;
+        if (name === undefined)
+            throw E.store_name_required();
+        assert.string(name);
+        if (!VALID_IDENTIFIER.test(name))
+            throw E.identifier_invalid(name);
+        assert.defined(db, E.db_missing);
+        assert.dict(schema);
+        assert.maybe.boolean(migrate);
+        assert.maybe.dict(init.extend);
+        this.#schema = schema;
+        this.#type = new StoreType(schema, pk);
+        this.#types = Object.fromEntries(Object.entries(schema).map(([key, value]) => [key, value.datatype]));
+        this.#name = name;
+        this.#db = db;
+        this.#pk = pk;
+        this.#generate_pk = generate_pk;
+        this.#fks = fks;
+        this.#relations = init.relations ?? {};
+        this.#migrate = migrate ?? true;
+        for (const relation of Object.keys(this.#relations)) {
+            if (relation in schema)
+                throw E.relation_conflicts_with_field(relation);
+        }
+        this.#nullables = new Set(Object.entries(this.#type.properties)
+            .filter(([, v]) => v.nullable)
+            .map(([k]) => k));
+        if (init.extend !== undefined) {
+            for (const [k, v] of Object.entries(init.extend)) {
+                if (k in this)
+                    throw E.key_duplicate(k);
+                this[k] = v;
+            }
+        }
+        registry.set(init.schema, this);
+    }
+    get #as() {
+        return {
+            table: this.name,
+            pk: this.#pk,
+            generate_pk: this.#generate_pk,
+            types: this.#types,
+        };
+    }
+    get table() {
+        const db = this.db;
+        const pk = {
+            name: this.#pk,
+            generate: this.#generate_pk,
+        };
+        return {
+            create: () => db.schema.create(this.#name, pk, this.#types),
+            delete: () => db.schema.delete(this.#name),
+        };
+    }
+    get infer() {
+        return undefined;
+    }
+    get schema() {
+        return this.#schema;
+    }
+    get type() {
+        return this.#type;
+    }
+    get migrate() {
+        return this.#migrate;
+    }
+    get name() {
+        return this.#name;
+    }
+    get pk() {
+        return this.#pk;
+    }
+    get db() {
+        return this.#db;
+    }
+    get types() {
+        return this.#types;
+    }
+    #parse_pk(pkv) {
+        const pk = this.#pk;
+        if (pk === null)
+            throw E.pk_undefined(this.name);
+        try {
+            this.#schema[pk].parse(pkv);
+        }
+        catch {
+            throw E.pk_invalid(pkv);
+        }
+        return pk;
+    }
+    #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;
+                case "uuid":
+                case "uuid_v4":
+                case "uuid_v7":
+                    if (!is.string(value))
+                        throw E.wrong_type("string", 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) {
+        const pk = this.#parse_pk(pkv);
+        return (await this.count({ where: { [pk]: pkv } })) === 1;
+    }
+    async get(pkv, options) {
+        const pk = this.#parse_pk(pkv);
+        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,
+        });
+        const n = records.length;
+        assert.true(n <= 1, E.record_number_invalid(n, "get"));
+        if (n === 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.#parse_pk(pkv);
+        const n = await this.db.update(this.#as, { set, where: { [pk]: pkv } });
+        assert.true(n === 1, E.record_number_invalid(n, "update"));
+    }
+    async #update_n(where, set) {
+        return await this.db.update(this.#as, { set, 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.#parse_pk(pkv);
+        const n = await this.db.delete(this.#as, { where: { [pk]: pkv } });
+        assert.true(n === 1, E.record_number_invalid(n, "delete"));
+    }
+    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 !== undefined ? [...options.select] : undefined,
+            limit: options?.limit,
+            sort: options?.sort,
+            with: this.#with(options?.with),
+        });
+        return result;
+    }
+    toJSON() {
+        return this.#type.toJSON();
+    }
+    extend(extensor) {
+        return new Store({
+            name: this.name,
+            db: this.db,
+            schema: this.#schema,
+            relations: this.#relations,
+            migrate: false,
+            extend: extensor(this),
+        });
+    }
+}
+function store(init) {
+    return new Store(init);
+}
+export default store;
+//# sourceMappingURL=store.js.map

package/lib/private/paths.d.ts

@@ -1,5 +1,5 @@
-import type FileRef from "@rcompat/fs/FileRef";
-import type Dict from "@rcompat/type/Dict";
+import type { FileRef } from "@rcompat/fs";
+import type { Dict } from "@rcompat/type";
 declare function resolve(root: FileRef, config_paths?: Dict<string[]>): Promise<any>;
 export default resolve;
 //# sourceMappingURL=paths.d.ts.map

package/lib/private/paths.js

@@ -1,4 +1,4 @@
-import fail from "#fail";
+import E from "#errors";
 import log from "#log";
 async function resolve(root, config_paths) {
     const tsconfig_path = root.join("tsconfig.json");
@@ -13,13 +13,13 @@ async function resolve(root, config_paths) {
             const config = JSON.parse(text);
             const ts_paths = config.compilerOptions?.paths ?? {};
             if (config_paths !== undefined && Object.keys(ts_paths).length > 0) {
-                return fail("tsconfig.json exists with paths, remove config paths");
+                return E.config_tsconfig_has_paths();
             }
             // merge with defaults (user paths override)
             return { ...ts_paths };
         }
         catch {
-            log.warn("Failed to parse tsconfig.json, falling back to config");
+            log.warn("failed to parse tsconfig.json, falling back to config");
         }
     }
     if (config_paths !== undefined)

package/lib/private/request/RequestBag.d.ts

@@ -1,9 +1,12 @@
-import type PartialDict from "@rcompat/type/PartialDict";
+import type { PartialDict } from "@rcompat/type";
 type Contents = PartialDict<string>;
 type Normalize = (key: string) => string;
 interface Schema<T> {
     parse(input: unknown): T;
 }
+interface CoercibleSchema<T> extends Schema<T> {
+    coerce(input: unknown): T;
+}
 type Options = {
     normalize?: Normalize;
     raw?: string;
@@ -67,6 +70,7 @@ export default class RequestBag {
      * @throws Whatever the schema throws.
      */
     parse<T>(schema: Schema<T>): T;
+    coerce<T>(schema: CoercibleSchema<T>): T;
     /** Returns {@link raw}. Useful in template strings. */
     toString(): string;
     /**

package/lib/private/request/RequestBag.js

@@ -1,5 +1,6 @@
-import fail from "#fail";
-import is from "@rcompat/assert/is";
+import E from "#errors";
+import assert from "@rcompat/assert";
+import fn from "@rcompat/fn";
 export default class RequestBag {
     #contents;
     #name;
@@ -12,16 +13,19 @@ export default class RequestBag {
      * @param name - Human-readable bag name used in error messages.
      * @param options - Optional `normalize` function and `raw` string.
      */
-    constructor(input, name, options = {}) {
-        is(input).object();
+    constructor(input, name, options) {
+        assert.dict(input);
+        assert.string(name);
+        assert.maybe.dict(options);
+        assert.maybe.function(options?.normalize);
+        assert.maybe.string(options?.raw);
         this.#name = name;
-        this.#normalize = options.normalize ?? (k => k);
-        this.#raw = options.raw ?? "";
+        this.#normalize = options?.normalize ?? fn.identity;
+        this.#raw = options?.raw ?? "";
         const contents = Object.create(null);
         for (const key of Object.keys(input)) {
-            const normalized = this.#normalize(key);
             // last-wins semantics if only case differs
-            contents[normalized] = input[key];
+            contents[this.#normalize(key)] = input[key];
         }
         this.#contents = contents;
     }
@@ -68,7 +72,7 @@ export default class RequestBag {
             if (v !== undefined)
                 return v;
         }
-        throw fail("{0} has no key {1}", this.#name, key);
+        throw E.request_bag_missing_key(this.#name, key);
     }
     /**
      * Try to get a value by key.
@@ -103,6 +107,9 @@ export default class RequestBag {
     parse(schema) {
         return schema.parse(this.#contents);
     }
+    coerce(schema) {
+        return schema.coerce(this.#contents);
+    }
     /** Returns {@link raw}. Useful in template strings. */
     toString() {
         return this.raw;

package/lib/private/request/RequestBody.d.ts

@@ -1,6 +1,4 @@
-import type Dict from "@rcompat/type/Dict";
-import type JSONValue from "@rcompat/type/JSONValue";
-import type Schema from "@rcompat/type/Schema";
+import type { Dict, JSONValue } from "@rcompat/type";
 type Form = Dict<string>;
 type Parsed = {
     type: "binary";
@@ -18,19 +16,16 @@ type Parsed = {
     type: "text";
     value: string;
 };
-type ParseReturn<S> = S extends {
-    parse: (v: unknown) => infer R;
-} ? R : never;
+declare function parse(request: Request, url: URL): Promise<RequestBody>;
+declare function none(): RequestBody;
 export default class RequestBody {
     #private;
-    static parse(request: Request, url: URL): Promise<RequestBody>;
-    static none(): RequestBody;
+    static parse: typeof parse;
+    static none: typeof none;
     constructor(parsed: Parsed, files?: Dict<File>);
-    get type(): "binary" | "form" | "json" | "none" | "text";
+    get type(): "json" | "binary" | "text" | "none" | "form";
     json(): JSONValue;
-    json<S extends Schema<unknown>>(schema: S): ParseReturn<S>;
     form(): Form;
-    form<S extends Schema<unknown>>(schema: S): ParseReturn<S>;
     files(): Dict<File>;
     text(): string;
     binary(): Blob;