@bunyad/orm 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/schema-types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Read a model's table from the database and (a) print a TypeScript interface for its
+ * columns, (b) report where the model and the table disagree.
+ *
+ * Used by `bunyad schema:types` and `bunyad schema:check`; usable directly in tests.
+ */
+import { type ColumnInfo, type Connection } from "@bunyad/database";
+import type { ModelClass } from "./model.js";
+type Driver = Connection["driver"];
+/** The TypeScript type a column hydrates to, taking the model's cast into account. */
+export declare function tsTypeForColumn(column: ColumnInfo, driver: Driver, cast?: unknown): string;
+/**
+ * `export interface UserColumns { id: number; … }` for one model. Pair it with the model class via
+ * declaration merging: `export interface User extends UserColumns {}`.
+ */
+export declare function modelColumnsInterface(model: ModelClass, connection?: Connection): Promise<string>;
+export type SchemaIssue = {
+    severity: "error" | "warning";
+    model: string;
+    table: string;
+    message: string;
+};
+/** Where a model's settings reference columns the table does not have. */
+export declare function checkModelSchema(model: ModelClass, connection?: Connection): Promise<SchemaIssue[]>;
+/** The whole `models.generated.ts` file for the given models. */
+export declare function generateModelTypes(models: ModelClass[], connection?: Connection): Promise<string>;
+export {};

package/dist/schema-types.js

@@ -0,0 +1,145 @@
+/**
+ * Read a model's table from the database and (a) print a TypeScript interface for its
+ * columns, (b) report where the model and the table disagree.
+ *
+ * Used by `bunyad schema:types` and `bunyad schema:check`; usable directly in tests.
+ */
+import { schemaFor } from "@bunyad/database";
+import { parseCast } from "./casts.js";
+/** The TypeScript type a column hydrates to, taking the model's cast into account. */
+export function tsTypeForColumn(column, driver, cast) {
+    let base = castType(cast) ?? databaseType(column.type.toLowerCase(), driver);
+    if (column.nullable && !column.primary)
+        base += " | null";
+    return base;
+}
+function castType(cast) {
+    if (typeof cast === "object" && cast !== null)
+        return null; // Attribute / enum: leave to the database type
+    if (typeof cast !== "string")
+        return null;
+    const parsed = parseCast(cast);
+    if (!parsed)
+        return null;
+    switch (parsed.type) {
+        case "boolean":
+        case "bool":
+            return "boolean";
+        case "integer":
+        case "int":
+        case "number":
+        case "float":
+        case "double":
+        case "real":
+            return "number";
+        case "decimal":
+            return parsed.arg !== undefined ? "string" : "number";
+        case "bigint":
+            return "bigint";
+        case "string":
+        case "hashed":
+        case "encrypted":
+            return "string";
+        case "date":
+        case "datetime":
+            return "Date";
+        case "json":
+            return "unknown";
+        case "array":
+            return "unknown[]";
+        case "collection":
+            return "Collection<unknown>";
+        default:
+            return "unknown"; // encrypted:json, encrypted:array, …
+    }
+}
+function databaseType(type, driver) {
+    const t = type.replace(/\(.*\)/, "").trim();
+    if (/^(bool|boolean)$/.test(t))
+        return driver === "sqlite" ? "number" : "boolean";
+    if (/^tinyint/.test(t))
+        return "number";
+    if (/^(smallint|integer|int|int2|int4|mediumint|serial|smallserial|float|real|double( precision)?|float4|float8)$/.test(t))
+        return "number";
+    if (/^(bigint|int8|bigserial)$/.test(t))
+        return "number | bigint";
+    if (/^(numeric|decimal|money)$/.test(t))
+        return "number | string"; // drivers disagree: some return exact strings
+    if (/^(date|datetime|timestamp|timestamptz|timestamp without time zone|timestamp with time zone)$/.test(t)) {
+        return driver === "sqlite" ? "string" : "Date";
+    }
+    if (/^(json|jsonb)$/.test(t))
+        return driver === "sqlite" ? "string" : "unknown";
+    if (/^(blob|bytea|binary|varbinary|longblob)$/.test(t))
+        return "Uint8Array";
+    return "string"; // text, varchar, char, uuid, enum, time, …
+}
+function modelName(model) {
+    return model.name || "Model";
+}
+/**
+ * `export interface UserColumns { id: number; … }` for one model. Pair it with the model class via
+ * declaration merging: `export interface User extends UserColumns {}`.
+ */
+export async function modelColumnsInterface(model, connection = model.getConnection()) {
+    const columns = await schemaFor(connection).getColumns(model.table);
+    if (columns.length === 0) {
+        throw new Error(`Table [${model.table}] does not exist (model ${modelName(model)}).`);
+    }
+    const casts = model.getCasts();
+    const lines = columns.map((c) => `  ${c.name}: ${tsTypeForColumn(c, connection.driver, casts[c.name])};`);
+    return `/** Columns of \`${model.table}\`. */\nexport interface ${modelName(model)}Columns {\n${lines.join("\n")}\n}\n`;
+}
+/** Where a model's settings reference columns the table does not have. */
+export async function checkModelSchema(model, connection = model.getConnection()) {
+    const name = modelName(model);
+    const table = model.table;
+    const issue = (severity, message) => ({ severity, model: name, table, message });
+    const columns = await schemaFor(connection).getColumns(table);
+    if (columns.length === 0)
+        return [issue("error", `table [${table}] does not exist`)];
+    const names = new Set(columns.map((c) => c.name));
+    const issues = [];
+    const list = (value) => (Array.isArray(value) ? value : []);
+    for (const [setting, values] of [["fillable", list(model.fillable)], ["guarded", list(model.guarded).filter((v) => v !== "*")], ["hidden", list(model.hidden)], ["visible", list(model.visible)]]) {
+        for (const column of values) {
+            if (!names.has(column))
+                issues.push(issue("error", `${setting} lists [${column}], which is not a column of [${table}]`));
+        }
+    }
+    for (const [column, cast] of Object.entries(model.getCasts())) {
+        // `Attribute.make` casts describe computed attributes; only plain casts must match a column.
+        if (typeof cast === "string" && !names.has(column))
+            issues.push(issue("error", `cast for [${column}] has no matching column in [${table}]`));
+    }
+    if (!names.has(model.primaryKey)) {
+        issues.push(issue("error", `primary key [${model.primaryKey}] is not a column of [${table}]`));
+    }
+    if (model.timestamps !== false) {
+        for (const column of ["created_at", "updated_at"]) {
+            if (!names.has(column))
+                issues.push(issue("error", `timestamps are on but [${table}] has no [${column}] column`));
+        }
+    }
+    if (model.softDeletes && !names.has("deleted_at")) {
+        issues.push(issue("error", `softDeletes is on but [${table}] has no [deleted_at] column`));
+    }
+    const known = new Set([...list(model.fillable), ...list(model.hidden), ...list(model.visible), model.primaryKey, "created_at", "updated_at", "deleted_at", ...Object.keys(model.getCasts())]);
+    const untracked = columns.filter((c) => !known.has(c.name) && !c.primary).map((c) => c.name);
+    if (untracked.length > 0 && list(model.fillable).length > 0) {
+        issues.push(issue("warning", `columns not in fillable, hidden or casts: ${untracked.join(", ")}`));
+    }
+    return issues;
+}
+/** The whole `models.generated.ts` file for the given models. */
+export async function generateModelTypes(models, connection) {
+    const sorted = [...models].sort((a, b) => modelName(a).localeCompare(modelName(b)));
+    const parts = [];
+    for (const model of sorted)
+        parts.push(await modelColumnsInterface(model, connection ?? model.getConnection()));
+    const body = parts.join("\n");
+    const header = "// Generated by `bunyad schema:types`. Do not edit; run it again after changing a migration.\n" +
+        (body.includes("Collection<") ? 'import type { Collection } from "@bunyad/common";\n' : "") +
+        "\n";
+    return header + body;
+}

package/dist/test-drivers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Real-database test harness: SQLite always; Postgres / MySQL when reachable.
+ * Set BUNYAD_TEST_POSTGRES_URL and/or BUNYAD_TEST_MYSQL_URL to enable them.
+ */
+import { type Connection } from "@bunyad/database";
+export interface TestDriver {
+    name: "sqlite" | "postgres" | "mysql";
+    connection: Connection;
+}
+export declare function testDrivers(): Promise<TestDriver[]>;

package/dist/test-drivers.js

@@ -0,0 +1,40 @@
+/**
+ * Real-database test harness: SQLite always; Postgres / MySQL when reachable.
+ * Set BUNYAD_TEST_POSTGRES_URL and/or BUNYAD_TEST_MYSQL_URL to enable them.
+ */
+import { connectMysql, connectPostgres, connectSqlite, } from "@bunyad/database";
+async function reachable(connection) {
+    try {
+        await connection.exec("SELECT 1");
+        return true;
+    }
+    catch (error) {
+        // A URL was configured but the server is unusable — say why instead of silently skipping.
+        console.warn(`[test-drivers] ${connection.driver} unavailable: ${error.message}`);
+        try {
+            await connection.close();
+        }
+        catch {
+            /* ignore */
+        }
+        return false;
+    }
+}
+export async function testDrivers() {
+    const drivers = [
+        { name: "sqlite", connection: connectSqlite() },
+    ];
+    const pg = Bun.env.BUNYAD_TEST_POSTGRES_URL ?? Bun.env.DATABASE_URL;
+    if (pg && /^(postgres|postgresql):\/\//i.test(pg)) {
+        const connection = connectPostgres({ url: pg, max: 2 });
+        if (await reachable(connection))
+            drivers.push({ name: "postgres", connection });
+    }
+    const my = Bun.env.BUNYAD_TEST_MYSQL_URL;
+    if (my && /^mysql:\/\//i.test(my)) {
+        const connection = connectMysql({ url: my, tls: { rejectUnauthorized: false } });
+        if (await reachable(connection))
+            drivers.push({ name: "mysql", connection });
+    }
+    return drivers;
+}

package/dist/typed-names.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Editor-hint types: relation and column names for a model, with a `string`
+ * fallback so dynamic names, `rel as alias`, nested `a.b` paths and
+ * `table.column` keep compiling. Typos still run; the editor just suggests
+ * the real names first.
+ */
+import type { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, MorphedByMany } from "./relations.js";
+import type { Model } from "./model.js";
+import type { OrmCollection } from "./orm-collection.js";
+import type { ModelQuery } from "./model-query.js";
+import type { OrmTypeOptions } from "./index.js";
+type AnyRelation = BelongsTo<any> | BelongsToMany<any> | HasMany<any> | HasManyThrough<any> | HasOne<any> | HasOneThrough<any> | MorphMany<any> | MorphOne<any> | MorphTo | MorphToMany<any> | MorphedByMany<any>;
+/**
+ * Relations of a model: methods that return a relation (`posts() { return this.hasMany(Post) }`)
+ * and declared relation properties (`declare posts: OrmCollection<Post>`, `declare author: User | null`),
+ * which is how models that define `static relations = { … }` describe them.
+ */
+export type RelationNames<T> = {
+    [K in Exclude<keyof T, keyof Model> & string]: T[K] extends () => AnyRelation ? K : T[K] extends (...args: any[]) => unknown ? never : [NonNullable<T[K]>] extends [never] ? never : NonNullable<T[K]> extends OrmCollection<any> | readonly Model[] | Model ? K : never;
+}[Exclude<keyof T, keyof Model> & string];
+/** Members `Model` itself declares that are really columns (every table has `id`). */
+type ModelOwnKeys = Exclude<keyof Model, "id">;
+/** Declared data fields on the model (`declare title: string`), excluding methods, plus the timestamp columns. */
+export type ColumnNames<T> = {
+    [K in Exclude<keyof T, ModelOwnKeys> & string]: T[K] extends (...args: any[]) => unknown ? never : K;
+}[Exclude<keyof T, ModelOwnKeys> & string] | "created_at" | "updated_at" | "deleted_at";
+/** Suggest `K` in the editor but accept any string. */
+export type Hint<K extends string> = K | (string & {});
+type StrictNames = OrmTypeOptions extends {
+    strictNames: false;
+} ? false : true;
+/**
+ * Strict relation name: a relation method, optionally with a nested path
+ * (`posts.comments`) or an alias (`posts as p`), so only typos in the first
+ * segment are rejected.
+ */
+type StrictRelation<T> = RelationNames<T> | `${RelationNames<T>}.${string}` | `${RelationNames<T>} as ${string}`;
+/** Strict column name: a declared field, or a qualified `table.column`. */
+type StrictColumn<T> = ColumnNames<T> | `${string}.${string}`;
+export type RelationHint<T> = StrictNames extends true ? Model extends T ? string : StrictRelation<T> : Hint<RelationNames<T>>;
+export type ColumnHint<T> = StrictNames extends true ? Model extends T ? string : StrictColumn<T> : Hint<ColumnNames<T>>;
+/** Escape hatch for a name only known at run time: `Post.with(unsafeName(input))`. */
+export declare function unsafeName(name: string): never;
+/**
+ * The `{ relation: constraint }` form of `with()`. Strict names check the keys like the
+ * string form and type the constraint callback; otherwise any record is accepted.
+ */
+export type WithMap<T> = StrictNames extends true ? Model extends T ? Record<string, unknown> : {
+    [K in StrictRelation<T>]?: true | string | {
+        as?: string;
+    } | ((query: ModelQuery) => void);
+} : Record<string, unknown>;
+export {};

package/dist/typed-names.js

@@ -0,0 +1,4 @@
+/** Escape hatch for a name only known at run time: `Post.with(unsafeName(input))`. */
+export function unsafeName(name) {
+    return name;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunyad/orm",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.2",
   "description": "Active-record ORM for Bunyad: models, relations, casts, scopes, events, factories.",
   "license": "MIT",
   "author": "Shah Khalid",
@@ -36,8 +36,8 @@
     }
   },
   "dependencies": {
-    "@bunyad/common": "^0.2.0-beta.0",
-    "@bunyad/database": "^0.2.0-beta.0"
+    "@bunyad/common": "^0.2.0-beta.2",
+    "@bunyad/database": "^0.2.0-beta.2"
   },
   "publishConfig": {
     "access": "public"