@bunyad/orm 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shah Khalid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @bunyad/orm
+
+Active-record models on top of [`@bunyad/database`](https://www.npmjs.com/package/@bunyad/database): relations, casts, scopes, events, soft deletes and factories. The same model code runs on Node and Bun.
+
+> **Alpha.** APIs may change between `0.x` releases.
+
+```bash
+npm install @bunyad/orm@alpha @bunyad/database@alpha better-sqlite3
+```
+
+## Quick start
+
+```ts
+import { connectSqlite, schemaFor } from "@bunyad/database";
+import { Model } from "@bunyad/orm";
+
+const connection = connectSqlite({ path: "app.sqlite" });
+Model.setConnection(connection);
+
+await schemaFor(connection).create("users", (table) => {
+  table.id();
+  table.string("name");
+  table.timestamps();
+});
+
+class User extends Model {
+  static table = "users";
+  static fillable = ["name"] as const;
+
+  declare id: number;
+  declare name: string;
+
+  posts() {
+    return this.hasMany(Post);
+  }
+}
+
+class Post extends Model {
+  static table = "posts";
+
+  user() {
+    return this.belongsTo(User);
+  }
+}
+
+const ada = await User.create({ name: "Ada" });
+await User.find(ada.id);
+await User.where("name", "Ada").first();
+await User.query().count();
+```
+
+Relations load lazily (`await user.posts().get()`) or eagerly (`User.with("posts")`).
+
+## Drivers
+
+Pick one and install it next to `@bunyad/database`: `better-sqlite3`, `pg` or `mysql2`. Bun uses its built-in drivers.
+
+## Framework glue
+
+- Express on Node: [`docs/examples/orm-node-express`](https://github.com/bunyadjs/framework/tree/main/docs/examples/orm-node-express)
+- Next.js (server-only, one shared pool): [`docs/examples/orm-node-next`](https://github.com/bunyadjs/framework/tree/main/docs/examples/orm-node-next)
+- NestJS: `@bunyad/nestjs` (`BunyadOrmModule`), in the monorepo and not published yet.
+
+## Status
+
+Alpha. SQLite is the most tested driver; PostgreSQL and MySQL tests need a live database and are skipped by default. Aggregate helpers such as `sumCase`/`countCase` are not implemented yet.
+
+## License
+
+MIT

package/dist/casts.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Attribute cast accessor/mutator (`Attribute.make`).
+ */
+export declare class Attribute {
+    readonly get?: (value: unknown, attributes: Record<string, unknown>) => unknown;
+    readonly set?: (value: unknown, attributes: Record<string, unknown>) => unknown | Record<string, unknown>;
+    constructor(options: {
+        get?: (value: unknown, attributes: Record<string, unknown>) => unknown;
+        set?: (value: unknown, attributes: Record<string, unknown>) => unknown | Record<string, unknown>;
+    });
+    /** `Attribute.make({ get, set })`. */
+    static make(options: {
+        get?: (value: unknown, attributes: Record<string, unknown>) => unknown;
+        set?: (value: unknown, attributes: Record<string, unknown>) => unknown | Record<string, unknown>;
+    }): Attribute;
+}
+/** Built-in cast type names. */
+export type CastType = "boolean" | "bool" | "number" | "integer" | "int" | "float" | "double" | "real" | "decimal" | "bigint" | "string" | "json" | "date" | "datetime" | "array" | "collection" | "encrypted" | "encrypted:array" | "encrypted:json" | "encrypted:collection" | "hashed";
+/**
+ * A TypeScript string/number enum object (or similar value map).
+ */
+export type EnumCast = Record<string, string | number>;
+/** Anything accepted in `casts` / `casts()`. */
+export type CastDefinition = CastType | EnumCast | Attribute;
+export declare function isCastType(value: unknown): value is CastType;
+export declare function isAttribute(value: unknown): value is Attribute;
+export declare function isEnumCast(value: unknown): value is EnumCast;
+/** Async bcrypt for the `hashed` cast (same output as the sync path, off the event loop). */
+export declare function hashCastValue(value: string): Promise<string>;
+export declare function isAlreadyHashed(value: string): boolean;
+export declare function castFromStorage(value: unknown, type: CastType): unknown;
+export declare function castToStorage(value: unknown, type: CastType, driver?: string): unknown;
+export declare function enumFromStorage(value: unknown, enumObj: EnumCast): unknown;
+export declare function enumToStorage(value: unknown, enumObj: EnumCast): unknown;
+/** Cast JSON column to a `Collection`. */
+export declare const AsCollection: Attribute;
+/** Cast JSON column to a `Fluent` bag. */
+export declare const AsFluent: Attribute;
+/**
+ * Cast a JSON array to a Collection of enum values.
+ *
+ * ```ts
+ * static casts() {
+ *   return { statuses: AsEnumCollection.of(Status) };
+ * }
+ * ```
+ */
+export declare const AsEnumCollection: {
+    of(enumObj: EnumCast): Attribute;
+};

package/dist/casts.js

@@ -0,0 +1,309 @@
+import { collect, Crypt, Fluent } from "@bunyad/common";
+import { dateForStorage, dateTimeForStorage, toDate, password as passwordPlatform, } from "@bunyad/database";
+/**
+ * Attribute cast accessor/mutator (`Attribute.make`).
+ */
+export class Attribute {
+    get;
+    set;
+    constructor(options) {
+        this.get = options.get;
+        this.set = options.set;
+    }
+    /** `Attribute.make({ get, set })`. */
+    static make(options) {
+        return new Attribute(options);
+    }
+}
+const CAST_TYPE_SET = new Set([
+    "boolean",
+    "bool",
+    "number",
+    "integer",
+    "int",
+    "float",
+    "double",
+    "real",
+    "decimal",
+    "bigint",
+    "string",
+    "json",
+    "date",
+    "datetime",
+    "array",
+    "collection",
+    "encrypted",
+    "encrypted:array",
+    "encrypted:json",
+    "encrypted:collection",
+    "hashed",
+]);
+function toNumber(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : 0;
+    }
+    if (typeof value === "bigint") {
+        return Number(value);
+    }
+    if (value === "" || value === null || value === undefined) {
+        return 0;
+    }
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+}
+/** JSON/sync often send `"0"` / `"false"`; those must not become true. */
+function toBoolean(value) {
+    if (value === true || value === 1 || value === 1n || value === "1") {
+        return true;
+    }
+    if (value === false || value === 0 || value === 0n || value === "0") {
+        return false;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "false" ||
+            normalized === "no" ||
+            normalized === "off" ||
+            normalized === "") {
+            return false;
+        }
+        if (normalized === "true" ||
+            normalized === "yes" ||
+            normalized === "on") {
+            return true;
+        }
+    }
+    return Boolean(value);
+}
+export function isCastType(value) {
+    return typeof value === "string" && CAST_TYPE_SET.has(value);
+}
+export function isAttribute(value) {
+    return value instanceof Attribute;
+}
+export function isEnumCast(value) {
+    if (value == null || typeof value !== "object")
+        return false;
+    if (isAttribute(value) || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return false;
+    return entries.every(([, v]) => typeof v === "string" || typeof v === "number");
+}
+function parseDateValue(value) {
+    return toDate(value);
+}
+/** Async bcrypt for the `hashed` cast (same output as the sync path, off the event loop). */
+export function hashCastValue(value) {
+    return passwordPlatform.hash(value, {
+        algorithm: "bcrypt",
+        cost: bcryptRounds(),
+    });
+}
+/** Same cost as `Hash.make`: `BCRYPT_ROUNDS`, default 10. */
+function bcryptRounds() {
+    return Number(process.env.BCRYPT_ROUNDS ?? 10);
+}
+export function isAlreadyHashed(value) {
+    return value.startsWith("$2") || value.startsWith("$argon2");
+}
+function collectionItems(value) {
+    if (value &&
+        typeof value === "object" &&
+        typeof value.all === "function") {
+        return value.all();
+    }
+    return Array.isArray(value) ? value : [];
+}
+function encryptPayload(plain) {
+    const text = typeof plain === "string" ? plain : JSON.stringify(plain);
+    return Crypt.encrypt(text);
+}
+function decryptPayload(value) {
+    if (typeof value !== "string")
+        return String(value ?? "");
+    return Crypt.decrypt(value);
+}
+export function castFromStorage(value, type) {
+    if (value == null)
+        return value;
+    switch (type) {
+        case "boolean":
+        case "bool":
+            return toBoolean(value);
+        case "number":
+        case "float":
+        case "double":
+        case "real":
+        case "decimal":
+            return toNumber(value);
+        case "integer":
+        case "int":
+            return Math.trunc(toNumber(value));
+        case "bigint":
+            return typeof value === "bigint" ? value : BigInt(String(value));
+        case "string":
+            return String(value);
+        case "json":
+        case "array":
+            return typeof value === "string" ? JSON.parse(value) : value;
+        case "collection": {
+            // From the database (JSON text), or already in memory: `fill()` passes a Collection or array.
+            const parsed = typeof value === "string" ? JSON.parse(value) : value;
+            return collect(collectionItems(parsed));
+        }
+        case "date":
+        case "datetime":
+            return parseDateValue(value);
+        case "encrypted":
+            return decryptPayload(value);
+        case "encrypted:json":
+        case "encrypted:array": {
+            const plain = decryptPayload(value);
+            return JSON.parse(plain);
+        }
+        case "encrypted:collection": {
+            const plain = decryptPayload(value);
+            const parsed = JSON.parse(plain);
+            return collect(Array.isArray(parsed) ? parsed : []);
+        }
+        case "hashed":
+            return value;
+        default:
+            return value;
+    }
+}
+export function castToStorage(value, type, driver) {
+    if (value == null)
+        return value;
+    const driverName = (driver ?? "sqlite");
+    switch (type) {
+        case "boolean":
+        case "bool": {
+            const flag = toBoolean(value);
+            if (driverName === "postgres")
+                return flag;
+            return flag ? 1 : 0;
+        }
+        case "number":
+        case "float":
+        case "double":
+        case "real":
+        case "decimal":
+            return toNumber(value);
+        case "integer":
+        case "int":
+            return Math.trunc(toNumber(value));
+        case "bigint":
+            return typeof value === "bigint" ? value : BigInt(String(value));
+        case "string":
+            return String(value);
+        case "json":
+        case "array":
+            return typeof value === "string" ? value : JSON.stringify(value);
+        case "collection": {
+            const items = collectionItems(value);
+            return JSON.stringify(items);
+        }
+        case "date":
+            return dateForStorage(value);
+        case "datetime":
+            return dateTimeForStorage(value, driverName);
+        case "encrypted":
+            return encryptPayload(value);
+        case "encrypted:json":
+        case "encrypted:array":
+            return encryptPayload(typeof value === "string" ? JSON.parse(value) : value);
+        case "encrypted:collection":
+            return encryptPayload(collectionItems(value));
+        case "hashed": {
+            if (typeof value !== "string" || value === "")
+                return value;
+            // Match prior ORM behaviour: never double-hash `$2…` / `$argon2…`.
+            if (isAlreadyHashed(value))
+                return value;
+            return passwordPlatform.hashSync(value, {
+                algorithm: "bcrypt",
+                cost: bcryptRounds(),
+            });
+        }
+        default:
+            return value;
+    }
+}
+export function enumFromStorage(value, enumObj) {
+    if (value == null)
+        return value;
+    for (const entry of Object.values(enumObj)) {
+        if (entry == value || String(entry) === String(value))
+            return entry;
+    }
+    return value;
+}
+export function enumToStorage(value, enumObj) {
+    if (value == null)
+        return value;
+    for (const entry of Object.values(enumObj)) {
+        if (entry === value)
+            return entry;
+    }
+    if (typeof value === "string" && value in enumObj) {
+        return enumObj[value];
+    }
+    return value;
+}
+/** Cast JSON column to a `Collection`. */
+export const AsCollection = Attribute.make({
+    get(value) {
+        return castFromStorage(value, "collection");
+    },
+    set(value) {
+        return castToStorage(value, "collection");
+    },
+});
+/** Cast JSON column to a `Fluent` bag. */
+export const AsFluent = Attribute.make({
+    get(value) {
+        if (value == null)
+            return new Fluent();
+        const parsed = typeof value === "string" ? JSON.parse(value) : value;
+        return new Fluent(parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {});
+    },
+    set(value) {
+        if (value instanceof Fluent)
+            return JSON.stringify(value.all());
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            return JSON.stringify(value);
+        }
+        return JSON.stringify({});
+    },
+});
+/**
+ * Cast a JSON array to a Collection of enum values.
+ *
+ * ```ts
+ * static casts() {
+ *   return { statuses: AsEnumCollection.of(Status) };
+ * }
+ * ```
+ */
+export const AsEnumCollection = {
+    of(enumObj) {
+        return Attribute.make({
+            get(value) {
+                if (value == null)
+                    return collect([]);
+                const parsed = typeof value === "string" ? JSON.parse(value) : value;
+                const list = Array.isArray(parsed) ? parsed : [];
+                return collect(list.map((item) => enumFromStorage(item, enumObj)));
+            },
+            set(value) {
+                const items = collectionItems(value).map((item) => enumToStorage(item, enumObj));
+                return JSON.stringify(items);
+            },
+        });
+    },
+};

package/dist/concerns.d.ts

@@ -0,0 +1,64 @@
+import type { ModelClass } from "./model.js";
+import type { Factory } from "./factory.js";
+/** Generate a UUIDv7 (time-ordered) string. */
+export declare function uuid7(): string;
+/** Generate a 26-character ULID. */
+export declare function ulid(now?: number): string;
+/**
+ * Ordered UUID primary keys (`incrementing = false`).
+ *
+ * @example
+ * ```ts
+ * @HasUuids()
+ * class Article extends Model {}
+ * ```
+ */
+export declare function HasUuids(): ClassDecorator;
+/**
+ * ULID primary keys (`incrementing = false`).
+ */
+export declare function HasUlids(): ClassDecorator;
+type FactoryClass = new () => Factory;
+type FactoryResolver = FactoryClass | (() => 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 declare function HasFactory(factory: FactoryResolver): ClassDecorator;
+/**
+ * Soft deletes — sets `static softDeletes = true`.
+ * Prefer this decorator for `use SoftDeletes`-style call sites.
+ */
+export declare function SoftDeletes(column?: string): ClassDecorator;
+/**
+ * Register for `model:prune` / `pruneAll()`.
+ * Define `static prunable()` returning the query of models to delete.
+ */
+export declare function Prunable(): ClassDecorator;
+/**
+ * Mass-delete via query (no model hydration / events).
+ */
+export declare function MassPrunable(): ClassDecorator;
+export declare function prunableModelClasses(): ModelClass[];
+export declare function massPrunableModelClasses(): ModelClass[];
+/** Clear registries (tests). */
+export declare function clearPrunableRegistries(): void;
+/** Prune one model class (`Model::pruneAll` for a single class). */
+export declare function prune(ModelClass: ModelClass, options?: {
+    chunk?: number;
+}): Promise<number>;
+/** Prune every registered `@Prunable` / `@MassPrunable` model. */
+export declare function pruneAll(options?: {
+    chunk?: number;
+}): Promise<Array<{
+    model: string;
+    count: number;
+}>>;
+export {};