@bunyad/orm 0.1.0-alpha.0

package/dist/concerns.js

@@ -0,0 +1,216 @@
+import { morphMap } from "./model.js";
+const HAS_UUIDS = Symbol.for("bunyad.orm.hasUuids");
+const HAS_ULIDS = Symbol.for("bunyad.orm.hasUlids");
+const PRUNABLE = Symbol.for("bunyad.orm.prunable");
+const MASS_PRUNABLE = Symbol.for("bunyad.orm.massPrunable");
+const prunableModels = new Set();
+const massPrunableModels = new Set();
+/** Crockford Base32 alphabet (ULID). */
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/** Generate a UUIDv7 (time-ordered) string. */
+export function uuid7() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    const ms = BigInt(Date.now());
+    bytes[0] = Number((ms >> 40n) & 0xffn);
+    bytes[1] = Number((ms >> 32n) & 0xffn);
+    bytes[2] = Number((ms >> 24n) & 0xffn);
+    bytes[3] = Number((ms >> 16n) & 0xffn);
+    bytes[4] = Number((ms >> 8n) & 0xffn);
+    bytes[5] = Number(ms & 0xffn);
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** Generate a 26-character ULID. */
+export function ulid(now = Date.now()) {
+    let time = now;
+    let out = "";
+    for (let i = 0; i < 10; i++) {
+        out = CROCKFORD[time % 32] + out;
+        time = Math.floor(time / 32);
+    }
+    const rand = new Uint8Array(16);
+    crypto.getRandomValues(rand);
+    for (let i = 0; i < 16; i++) {
+        out += CROCKFORD[rand[i] % 32];
+    }
+    return out;
+}
+function asConcern(target) {
+    return target;
+}
+function assignUniqueIds(model, ctor) {
+    const keys = ctor.uniqueIds?.() ?? [ctor.primaryKey];
+    const row = model;
+    for (const key of keys) {
+        if (row[key] == null || row[key] === "") {
+            row[key] = ctor.newUniqueId?.() ?? uuid7();
+        }
+    }
+}
+/**
+ * Ordered UUID primary keys (`incrementing = false`).
+ *
+ * @example
+ * ```ts
+ * @HasUuids()
+ * class Article extends Model {}
+ * ```
+ */
+export function HasUuids() {
+    return (target) => {
+        const ctor = asConcern(target);
+        ctor[HAS_UUIDS] = true;
+        ctor.incrementing = false;
+        ctor.keyType = "string";
+        ctor.newUniqueId = () => uuid7();
+        ctor.uniqueIds = () => [ctor.primaryKey];
+        morphMap({ [ctor.name]: ctor });
+        ctor.creating((model) => assignUniqueIds(model, ctor));
+    };
+}
+/**
+ * ULID primary keys (`incrementing = false`).
+ */
+export function HasUlids() {
+    return (target) => {
+        const ctor = asConcern(target);
+        ctor[HAS_ULIDS] = true;
+        ctor.incrementing = false;
+        ctor.keyType = "string";
+        ctor.newUniqueId = () => ulid();
+        ctor.uniqueIds = () => [ctor.primaryKey];
+        morphMap({ [ctor.name]: ctor });
+        ctor.creating((model) => assignUniqueIds(model, ctor));
+    };
+}
+function resolveFactory(factory) {
+    if (typeof factory === "function" &&
+        factory.prototype != null &&
+        typeof factory.prototype.model === "function") {
+        return new factory();
+    }
+    return factory();
+}
+/**
+ * Bind a factory class and expose `Model.factory()`.
+ *
+ * @example
+ * ```ts
+ * @HasFactory(UserFactory)
+ * // or @HasFactory(() => new UserFactory())
+ * class User extends Model {}
+ * User.factory().create();
+ * ```
+ */
+export function HasFactory(factory) {
+    return (target) => {
+        const ctor = asConcern(target);
+        ctor.factory = () => resolveFactory(factory);
+    };
+}
+/**
+ * Soft deletes — sets `static softDeletes = true`.
+ * Prefer this decorator for `use SoftDeletes`-style call sites.
+ */
+export function SoftDeletes(column = "deleted_at") {
+    return (target) => {
+        const ctor = asConcern(target);
+        ctor.softDeletes = true;
+        ctor.deletedAt = column;
+    };
+}
+/**
+ * Register for `model:prune` / `pruneAll()`.
+ * Define `static prunable()` returning the query of models to delete.
+ */
+export function Prunable() {
+    return (target) => {
+        const ctor = asConcern(target);
+        ctor[PRUNABLE] = true;
+        prunableModels.add(ctor);
+    };
+}
+/**
+ * Mass-delete via query (no model hydration / events).
+ */
+export function MassPrunable() {
+    return (target) => {
+        const ctor = asConcern(target);
+        ctor[MASS_PRUNABLE] = true;
+        massPrunableModels.add(ctor);
+    };
+}
+export function prunableModelClasses() {
+    return [...prunableModels];
+}
+export function massPrunableModelClasses() {
+    return [...massPrunableModels];
+}
+/** Clear registries (tests). */
+export function clearPrunableRegistries() {
+    prunableModels.clear();
+    massPrunableModels.clear();
+}
+async function pruneOne(ModelClass, options = {}) {
+    const ctor = ModelClass;
+    if (typeof ctor.prunable !== "function") {
+        throw new Error(`Model [${ModelClass.name}] is prunable but does not define static prunable().`);
+    }
+    const chunk = options.chunk ?? 1000;
+    let total = 0;
+    if (options.mass || ModelClass[MASS_PRUNABLE]) {
+        const query = await ctor.prunable();
+        if (ModelClass.softDeletes) {
+            total += await query.forceDelete();
+        }
+        else {
+            total += await query.delete();
+        }
+        return total;
+    }
+    for (;;) {
+        const query = await ctor.prunable();
+        const models = await query.limit(chunk).get();
+        if (models.isEmpty())
+            break;
+        for (const model of models) {
+            await ctor.pruning?.(model);
+            if (ModelClass.softDeletes) {
+                await model.forceDelete();
+            }
+            else {
+                await model.delete();
+            }
+            total += 1;
+        }
+        if (models.length < chunk)
+            break;
+    }
+    return total;
+}
+/** Prune one model class (`Model::pruneAll` for a single class). */
+export async function prune(ModelClass, options = {}) {
+    return pruneOne(ModelClass, options);
+}
+/** Prune every registered `@Prunable` / `@MassPrunable` model. */
+export async function pruneAll(options = {}) {
+    const results = [];
+    for (const ModelClass of massPrunableModels) {
+        results.push({
+            model: ModelClass.name,
+            count: await pruneOne(ModelClass, { ...options, mass: true }),
+        });
+    }
+    for (const ModelClass of prunableModels) {
+        if (massPrunableModels.has(ModelClass))
+            continue;
+        results.push({
+            model: ModelClass.name,
+            count: await pruneOne(ModelClass, options),
+        });
+    }
+    return results;
+}

package/dist/decorators.d.ts

@@ -0,0 +1,7 @@
+import type { ModelClass, ModelQuery, ModelQueryOptions } from "./model.js";
+export type ModelBuilderConstructor = new (model: ModelClass, options?: ModelQueryOptions) => ModelQuery;
+/**
+ * Use a custom `ModelQuery` subclass for this model’s `newQuery()` / `where()` / …
+ */
+export declare function UseBuilder(builder: ModelBuilderConstructor): ClassDecorator;
+export declare function resolveModelBuilder(model: Function): ModelBuilderConstructor | undefined;

package/dist/decorators.js

@@ -0,0 +1,12 @@
+const MODEL_BUILDER = Symbol.for("bunyad.orm.modelBuilder");
+/**
+ * Use a custom `ModelQuery` subclass for this model’s `newQuery()` / `where()` / …
+ */
+export function UseBuilder(builder) {
+    return (target) => {
+        target[MODEL_BUILDER] = builder;
+    };
+}
+export function resolveModelBuilder(model) {
+    return model[MODEL_BUILDER];
+}

package/dist/eager-fetch.d.ts

@@ -0,0 +1,7 @@
+import { Model, type ModelClass } from "./model.js";
+/**
+ * Fetch related models by key IN (...) for eager load.
+ * Prefer raw SQL + light hydrate (matches ofMany) when the related model has
+ * no global scopes; fall back to ModelQuery when scopes must run.
+ */
+export declare function eagerFetchByKeys(Related: ModelClass, keyColumn: string, ids: unknown[]): Promise<Model[]>;

package/dist/eager-fetch.js

@@ -0,0 +1,38 @@
+/**
+ * Shared key IN (...) fetch for eager load and HasManyThrough lazy get.
+ */
+import { wrapSqlName } from "@bunyad/database";
+import { hasGlobalScopes } from "./scopes.js";
+import { softDeleteAliasSql } from "./model-helpers.js";
+import { Model } from "./model.js";
+/**
+ * Fetch related models by key IN (...) for eager load.
+ * Prefer raw SQL + light hydrate (matches ofMany) when the related model has
+ * no global scopes; fall back to ModelQuery when scopes must run.
+ */
+export async function eagerFetchByKeys(Related, keyColumn, ids) {
+    if (ids.length === 0)
+        return [];
+    if (hasGlobalScopes(Related)) {
+        const collection = await Related.whereIn(keyColumn, ids).get();
+        return collection.all();
+    }
+    const conn = Related.getConnection();
+    const dialect = conn.dialect;
+    const table = wrapSqlName(dialect, Related.table);
+    const key = wrapSqlName(dialect, keyColumn);
+    const soft = softDeleteAliasSql(Related, table);
+    const placeholders = ids.map(() => "?").join(", ");
+    const sql = `SELECT ${table}.* FROM ${table} WHERE ${table}.${key} IN (${placeholders})${soft}`;
+    // Prefer sync SQLite reads — matches BelongsTo().first() → find() hot path.
+    const rows = (conn.allSync
+        ? conn.allSync(sql, ids)
+        : await conn.all(sql, ids));
+    const models = new Array(rows.length);
+    for (let i = 0; i < rows.length; i++) {
+        const model = new Related(rows[i]);
+        model.exists = true;
+        models[i] = model;
+    }
+    return models;
+}

package/dist/eager.d.ts

@@ -0,0 +1,24 @@
+import { type NormalizedEagerRelation } from "./model-helpers.js";
+import { Model } from "./model.js";
+/** Eager-load named relations onto models (`with` / `load` / collections).
+ * Batches BelongsTo / HasMany / HasOne / BelongsToMany / Morph* / ofMany with
+ * `WHERE IN`. Nested paths like `parent.children` are supported.
+ * Independent top-level relations load in parallel.
+ * Constraints from `with({ posts: (q) => q.where(…) })` are applied per relation.
+ */
+/**
+ * Eager-load relations onto models.
+ * Returns void when all work is synchronous (SQLite BelongsTo fast-find),
+ * otherwise a Promise — callers must branch like `get()` hydrate does.
+ */
+export declare function eagerLoadModels(models: Model[], relations: Array<string | NormalizedEagerRelation>): void | Promise<void>;
+type AggregateFn = "count" | "sum" | "avg" | "min" | "max" | "exists";
+export type EagerAggregateSpec = {
+    relation: string;
+    alias: string;
+    fn: AggregateFn;
+    column?: string;
+};
+/** Batch `loadCount` / `loadSum` / … onto many models (one GROUP BY query per relation). */
+export declare function eagerLoadAggregates(models: Model[], specs: EagerAggregateSpec[]): Promise<void>;
+export {};