@zerotal/orm 1.0.0

package/src/config.ts

@@ -0,0 +1,182 @@
+import { deepMerge } from "@zerotal/core";
+import type { ConfigValidator, ConfigIssue } from "@zerotal/core/config";
+
+/**
+ * Shape of the `database` config namespace produced by {@link DatabaseConfig}.
+ * Consumed by {@link DatabaseProvider} to build the connection, read replicas,
+ * pool, and auto-sync behaviour.
+ */
+export interface DatabaseConfigShape {
+  /** Database driver. Default: 'sqlite' */
+  driver: "sqlite" | "postgres" | "mysql";
+  /** Connection URL. Default: './database/db.sqlite' */
+  url: string;
+  /**
+   * Read-replica connection URLs.
+   *
+   * When one or more replicas are configured, the ORM automatically routes
+   * SELECT / WITH / EXPLAIN queries to replicas (round-robin) and all
+   * mutating queries (INSERT, UPDATE, DELETE, DDL) plus transactions to the
+   * primary. No code changes are required in controllers or models.
+   *
+   * @example
+   * replicas: [
+   *   env('REPLICA_1_URL'),
+   *   env('REPLICA_2_URL'),
+   * ]
+   */
+  replicas?: string[];
+  /**
+   * Connection pool options (PostgreSQL and MySQL only).
+   * Bun.sql manages the pool automatically - these tune its behaviour.
+   */
+  pool?: {
+    /** Maximum number of connections in the pool. Default: 10 */
+    max?: number;
+    /** Seconds an idle connection is kept before being closed. Default: 30 */
+    idleTimeout?: number;
+  };
+  /** SQLite-specific options */
+  sqlite: {
+    /** Path to the SQLite file. Use ':memory:' for in-memory database. */
+    path: string;
+  };
+  /**
+   * Auto-sync the schema to your models at boot (TypeORM-style). Opt-in, and
+   * hard-off in production regardless of this value.
+   *
+   * - `false` (default): never sync; use generated migrations.
+   * - `true`: additive sync - create missing tables, add missing columns. Never drops.
+   * - `{ enabled, disruptive }`: set `disruptive: true` to also DROP columns that no
+   *   model declares anymore (destroys their data - local/test only).
+   *
+   * @example
+   * synchronize: env("APP_ENV") !== "production"          // additive
+   * synchronize: { enabled: true, disruptive: false }     // explicit, additive
+   * synchronize: { enabled: true, disruptive: true }      // also drops removed columns
+   */
+  synchronize?: boolean | { enabled: boolean; disruptive?: boolean };
+}
+
+const defaults: DatabaseConfigShape = {
+  driver: "sqlite",
+  url: "./database/db.sqlite",
+  sqlite: { path: "./database/db.sqlite" },
+};
+
+/**
+ * Create a typed database configuration object with defaults.
+ *
+ * IMPORTANT: For SQLite, do NOT use a 'sqlite://' protocol prefix.
+ * Bun's native SQLite driver expects a raw file path or ':memory:'.
+ *
+ * @example
+ * import { DatabaseConfig } from '@zerotal/orm';
+ * export default DatabaseConfig({
+ *   driver: 'sqlite',
+ *   url:    env('DATABASE_URL', './database/db.sqlite'),
+ * });
+ */
+export function DatabaseConfig(options: Partial<DatabaseConfigShape> = {}): DatabaseConfigShape {
+  return deepMerge(defaults, options);
+}
+
+const DRIVERS = new Set<string>(["sqlite", "postgres", "mysql"]);
+
+/**
+ * Validate the `database` config namespace at boot. Catches driver/URL protocol
+ * mismatches in any environment (they can never work), and flags
+ * production-specific hazards — an in-memory database that vanishes on restart,
+ * a `synchronize` flag that is silently ignored — as warnings. Registered by
+ * {@link DatabaseProvider} via `app.registerConfigValidator("database", …)`.
+ */
+export const validateDatabaseConfig: ConfigValidator = (value, { isProduction }) => {
+  const cfg = value as Partial<DatabaseConfigShape> | undefined;
+  const issues: ConfigIssue[] = [];
+  const driver = cfg?.driver ?? "sqlite";
+  const url = cfg?.url ?? "";
+
+  if (!DRIVERS.has(driver)) {
+    issues.push({
+      level: "error",
+      message: `database.driver "${driver}" is not a supported dialect — use "sqlite", "postgres", or "mysql".`,
+    });
+    return issues;
+  }
+
+  const looksPostgres = /^postgres(ql)?:\/\//.test(url);
+  const looksMysql = /^mysql2?:\/\//.test(url);
+  if (driver === "postgres" && url && !looksPostgres) {
+    issues.push({
+      level: "error",
+      message:
+        `database.driver is "postgres" but database.url does not start with postgres:// — ` +
+        `set DATABASE_URL to a PostgreSQL connection URL.`,
+    });
+  }
+  if (driver === "mysql" && url && !looksMysql) {
+    issues.push({
+      level: "error",
+      message:
+        `database.driver is "mysql" but database.url does not start with mysql:// — ` +
+        `set DATABASE_URL to a MySQL connection URL.`,
+    });
+  }
+  if (driver === "sqlite" && (looksPostgres || looksMysql)) {
+    issues.push({
+      level: "error",
+      message:
+        `database.driver is "sqlite" but database.url points at a network database — ` +
+        `set driver to match the URL, or point url at a file path.`,
+    });
+  }
+
+  if (isProduction) {
+    if (driver === "sqlite" && (url === ":memory:" || cfg?.sqlite?.path === ":memory:")) {
+      issues.push({
+        level: "warning",
+        message:
+          "database uses an in-memory SQLite store in production — every restart loses all data. " +
+          "Point database.url at a file path or a network database.",
+      });
+    }
+    const sync = cfg?.synchronize;
+    if (sync === true || (typeof sync === "object" && sync !== null && sync.enabled)) {
+      issues.push({
+        level: "warning",
+        message:
+          "database.synchronize is enabled but auto-sync is hard-off in production — " +
+          "the flag does nothing here. Ship schema changes as migrations.",
+      });
+    }
+  }
+
+  const replicas = cfg?.replicas ?? [];
+  if (replicas.length > 0) {
+    if (driver === "sqlite") {
+      issues.push({
+        level: "warning",
+        message:
+          "database.replicas is set with the sqlite driver — read/write splitting is for " +
+          "network databases; the replica list adds no redundancy to a local file.",
+      });
+    }
+    if (replicas.some((r) => typeof r !== "string" || r.length === 0)) {
+      issues.push({
+        level: "error",
+        message:
+          "database.replicas contains an empty entry — an unset environment variable is the " +
+          "usual culprit. Every replica must be a full connection URL.",
+      });
+    }
+  }
+
+  return issues;
+};
+
+// Register this package's config namespace for typed `config()` dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    database: DatabaseConfigShape;
+  }
+}

package/src/conventions.ts

@@ -0,0 +1,67 @@
+import type { ConcernDescriptor } from "@zerotal/core";
+import { tableNameFor } from "@zerotal/core";
+import { BaseModel } from "./model/BaseModel.ts";
+import { registerModel, modelByName } from "./model/decorators/_metadata.ts";
+import { frameworkLog } from "@zerotal/core/logger";
+
+function isModelClass(v: unknown): boolean {
+  return (
+    typeof v === "function" &&
+    v !== BaseModel &&
+    (v as { prototype?: unknown }).prototype instanceof BaseModel
+  );
+}
+
+/**
+ * `app/models/` — every `BaseModel` subclass is registered: columns drained, table name
+ * derived by convention (unless `@table`/`static table` set one), indexed by class name.
+ * Runs first (order 10) so observers/policies can resolve their target model by name.
+ * @internal
+ */
+export const modelsConcern: ConcernDescriptor = {
+  name: "models",
+  order: 10,
+  dir: "app/models",
+  register(mod) {
+    for (const exported of Object.values(mod)) {
+      if (!isModelClass(exported)) continue;
+      const Model = exported as unknown as { name: string; table?: string };
+      registerModel(Model as unknown as Function);
+      // Convention table name — explicit @table / static table always wins.
+      if (!Model.table) Model.table = tableNameFor(Model.name);
+    }
+  },
+};
+
+/**
+ * `app/observers/` — `XObserver` is attached to model `X` (strip the `Observer` suffix and
+ * look it up in the model registry). Override with `static model = SomeModel`.
+ * @internal
+ */
+export const observersConcern: ConcernDescriptor = {
+  name: "observers",
+  order: 20,
+  dir: "app/observers",
+  register(mod) {
+    for (const exported of Object.values(mod)) {
+      if (typeof exported !== "function") continue;
+      const cls = exported as { name: string; model?: unknown };
+      if (cls.model === undefined && !/Observer$/.test(cls.name)) continue;
+
+      let model = cls.model as typeof BaseModel | undefined;
+      if (!model)
+        model = modelByName(cls.name.replace(/Observer$/, "")) as typeof BaseModel | undefined;
+      if (!model) {
+        frameworkLog("orm").warn(`Observer "${cls.name}": no matching model found; skipped`);
+        continue;
+      }
+      model.observe(exported as never);
+    }
+  },
+};
+
+/**
+ * The ORM's convention concerns, registered by {@link DatabaseProvider} in order.
+ * @internal
+ */
+export const ormConcerns: ConcernDescriptor[] = [modelsConcern, observersConcern];