@arkstack/database 0.12.36 → 0.13.0

package/dist/arkorm-BdOIitRp.js

@@ -0,0 +1,176 @@
+import { Arkorm, DB, Model, createKyselyAdapter, defineConfig } from "arkormx";
+import { IDatabaseDriver } from "kanun";
+import { config, outputDir } from "@arkstack/common";
+import { Pool } from "pg";
+import { Kysely, PostgresDialect } from "kysely";
+import { Arkstack } from "@arkstack/contract";
+import { createArkormCurrentPageResolver } from "resora";
+import { existsSync } from "node:fs";
+import path from "node:path";
+//#region src/ValidatorDBDriver.ts
+var ValidatorDBDriver = class extends IDatabaseDriver {
+	async exists({ table, column, value, ignore }) {
+		try {
+			const query = DB.table(table).where({ [column]: value });
+			if (ignore) query.whereNot({ [column]: ignore });
+			return await query.exists();
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* Read a value from the `database` configuration namespace with a fallback.
+*
+* Never throws when the config file is missing; returns the default instead.
+*
+* @param key           Dot path within the database config.
+* @param defaultValue  Value returned when the key is not set.
+*/
+const configure = (key, defaultValue) => {
+	try {
+		return config(`database.${key}`, defaultValue);
+	} catch {
+		return defaultValue;
+	}
+};
+/**
+* Resolve a configured {@link ConnectionConfig} by name, or the default
+* connection when none is given.
+*
+* @param name  The connection name. Defaults to `database.default`.
+* @throws when the named connection is not configured.
+*/
+const resolveConnection = (name) => {
+	const connection = name ?? configure("default", "pgsql");
+	const resolved = configure("connections", {})[connection];
+	if (!resolved) throw new Error(`Database connection "${connection}" is not configured.`);
+	return resolved;
+};
+//#endregion
+//#region src/kysely.ts
+/**
+* Build a pg {@link Pool} from a {@link ConnectionConfig}. A `url` (or
+* `DATABASE_URL`) wins over the discrete `host`/`port`/`user`/... fields.
+* 
+* @param connection 
+* @returns 
+*/
+const createPool = (connection) => {
+	const poolConfig = connection.url ? { connectionString: connection.url } : {
+		host: connection.host,
+		port: connection.port,
+		user: connection.user,
+		database: connection.database,
+		password: connection.password
+	};
+	if (connection.ssl !== void 0) poolConfig.ssl = connection.ssl;
+	if (connection.pool?.max !== void 0) poolConfig.max = connection.pool.max;
+	if (connection.pool?.idleTimeoutMillis !== void 0) poolConfig.idleTimeoutMillis = connection.pool.idleTimeoutMillis;
+	if (connection.pool?.connectionTimeoutMillis !== void 0) poolConfig.connectionTimeoutMillis = connection.pool.connectionTimeoutMillis;
+	return new Pool(poolConfig);
+};
+/**
+* Build a Kysely instance for the given connection using the Postgres dialect.
+* 
+* @param connection 
+* @returns 
+*/
+const createKysely = (connection) => {
+	return new Kysely({ dialect: new PostgresDialect({ pool: createPool(connection) }) });
+};
+/**
+* Build an ArkORM Kysely adapter for the given connection. This is what binds
+* models to the database.
+* 
+* @param connection 
+* @returns 
+*/
+const createAdapter = (connection) => {
+	return createKyselyAdapter(createKysely(connection));
+};
+//#endregion
+//#region src/arkorm.ts
+/**
+* Default ArkORM paths matching the scaffolded application structure. Apps with
+* a different layout can override them by adding an `arkormx.config.ts`.
+*/
+const defaultPaths = () => {
+	return {
+		models: "./src/app/models",
+		factories: "./src/database/factories",
+		seeders: "./src/database/seeders",
+		migrations: "./src/database/migrations",
+		buildOutput: path.relative(Arkstack.rootDir(), outputDir())
+	};
+};
+/**
+* Whether the application provides its own `arkormx.config.{ts,js}`. When it
+* does, ArkORM loads it and it takes precedence over the framework defaults.
+*/
+const hasUserArkormConfig = () => {
+	const root = Arkstack.rootDir();
+	return existsSync(path.join(root, "arkormx.config.ts")) || existsSync(path.join(root, "arkormx.config.js"));
+};
+/**
+* Build the ArkORM config object for an application from its database
+* configuration. Use this only when authoring an explicit `arkormx.config.ts`;
+* by default the framework configures ArkORM for you (see {@link bootArkorm}).
+*
+* @param options  Arkorm config plus the app's database config.
+*/
+const defineArkormConfig = (options = {}) => {
+	const { database, connection, adapter, pagination, ...rest } = options;
+	let resolvedAdapter = adapter;
+	if (!resolvedAdapter && database) {
+		const name = connection ?? database.default;
+		const resolved = database.connections[name];
+		if (!resolved) throw new Error(`Database connection "${name}" is not configured.`);
+		resolvedAdapter = createAdapter(resolved);
+	}
+	return defineConfig({
+		...rest,
+		...resolvedAdapter ? { adapter: resolvedAdapter } : {},
+		pagination: {
+			resolveCurrentPage: createArkormCurrentPageResolver(),
+			...pagination ?? {}
+		}
+	});
+};
+/**
+* Configure ArkORM natively from `src/config/database.ts`, so applications work
+* without an `arkormx.config.ts`.
+*
+* Builds the adapter from the default (or named) connection, registers the
+* conventional paths and the resora pagination resolver, and binds models. A
+* user-provided `arkormx.config.{ts,js}` always wins — in that case this is a
+* no-op and ArkORM loads the file instead.
+*
+* @param options  Optional overrides merged over the derived config.
+* @returns        Whether the framework applied its configuration.
+*/
+const bootArkorm = (options = {}) => {
+	if (hasUserArkormConfig()) return false;
+	const { connection, adapter, paths, pagination, ...rest } = options;
+	const resolvedAdapter = adapter ?? createAdapter(resolveConnection(connection));
+	Arkorm.configure({
+		adapter: resolvedAdapter,
+		paths: {
+			...defaultPaths(),
+			...paths ?? {}
+		},
+		pagination: {
+			resolveCurrentPage: createArkormCurrentPageResolver(),
+			...pagination ?? {}
+		},
+		outputExt: "ts",
+		...rest
+	});
+	Model.setAdapter(resolvedAdapter);
+	DB.setAdapter(resolvedAdapter);
+	return true;
+};
+//#endregion
+export { createPool as a, ValidatorDBDriver as c, createKysely as i, defineArkormConfig as n, configure as o, createAdapter as r, resolveConnection as s, bootArkorm as t };

package/dist/commands/MakeFactoryCommand.js

@@ -1,4 +1,4 @@
-import { t as Rebuilder } from "./Rebuilder-a3FLKQ9t.js";
+import { t as Rebuilder } from "./chunks/Rebuilder-DiWBr60E.js";
 import { CliApp, MakeFactoryCommand as MakeFactoryCommand$1 } from "arkormx";
 //#region src/commands/MakeFactoryCommand.ts
 var MakeFactoryCommand = class extends MakeFactoryCommand$1 {

package/dist/commands/MakeMigrationCommand.js

@@ -1,4 +1,4 @@
-import { t as Rebuilder } from "./Rebuilder-a3FLKQ9t.js";
+import { t as Rebuilder } from "./chunks/Rebuilder-DiWBr60E.js";
 import { CliApp, MakeMigrationCommand as MakeMigrationCommand$1 } from "arkormx";
 //#region src/commands/MakeMigrationCommand.ts
 var MakeMigrationCommand = class extends MakeMigrationCommand$1 {

package/dist/commands/MakeModelCommand.js

@@ -1,4 +1,4 @@
-import { t as Rebuilder } from "./Rebuilder-a3FLKQ9t.js";
+import { t as Rebuilder } from "./chunks/Rebuilder-DiWBr60E.js";
 import { CliApp, MakeModelCommand as MakeModelCommand$1 } from "arkormx";
 //#region src/commands/MakeModelCommand.ts
 var MakeModelCommand = class extends MakeModelCommand$1 {

package/dist/commands/MakeSeederCommand.js

@@ -1,4 +1,4 @@
-import { t as Rebuilder } from "./Rebuilder-a3FLKQ9t.js";
+import { t as Rebuilder } from "./chunks/Rebuilder-DiWBr60E.js";
 import { CliApp, MakeSeederCommand as MakeSeederCommand$1 } from "arkormx";
 //#region src/commands/MakeSeederCommand.ts
 var MakeSeederCommand = class extends MakeSeederCommand$1 {

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-import { DB as DB$1, FactoryAttributes, Migration as Migration$1, Model as Model$1, ModelAttributes, ModelAttributesOf, ModelFactory as ModelFactory$1, ModelQuerySchemaLike, SchemaBuilder as SchemaBuilder$1, Seeder as Seeder$1 } from "arkormx";
+import * as _$arkormx from "arkormx";
+import { ArkormConfig, DB as DB$1, FactoryAttributes, Migration as Migration$1, Model as Model$1, ModelAttributes, ModelAttributesOf, ModelFactory as ModelFactory$1, ModelQuerySchemaLike, SchemaBuilder as SchemaBuilder$1, Seeder as Seeder$1 } from "arkormx";
 import { IDatabaseDriver, ValidationDatabaseExistsInput } from "kanun";
+import { DotPath, DotPathValue } from "@arkstack/common";
+import { Pool } from "pg";
+import { Kysely } from "kysely";
 
 //#region src/extensions/DB.d.ts
 declare class DB extends DB$1 {}
@@ -29,4 +33,135 @@ declare class ValidatorDBDriver extends IDatabaseDriver {
   }: ValidationDatabaseExistsInput): Promise<boolean>;
 }
 //#endregion
-export { DB, Migration, Model, ModelFactory, SchemaBuilder, Seeder, ValidatorDBDriver };
+//#region src/types.d.ts
+/**
+ * A connection password. pg accepts a static string or a (possibly async)
+ * function that resolves one, which is useful for rotating credentials / IAM
+ * auth tokens.
+ */
+type ConnectionPassword = string | (() => string | Promise<string>);
+/**
+ * A single database connection's settings.
+ *
+ * Credentials are provided as discrete fields (`host`, `port`, `user`,
+ * `database`, `password`). When `url` (or `DATABASE_URL`) is set it takes
+ * precedence and the discrete fields are ignored.
+ */
+interface ConnectionConfig {
+  /** The SQL driver. Only `postgres` is wired up today. */
+  driver?: 'postgres' | 'pgsql';
+  /** A full connection string. Overrides the discrete fields when set. */
+  url?: string;
+  host?: string;
+  port?: number;
+  user?: string;
+  database?: string;
+  password?: ConnectionPassword;
+  /** pg SSL options: `true`, or a TLS options object. */
+  ssl?: boolean | Record<string, unknown>;
+  /** pg pool tuning. */
+  pool?: {
+    max?: number;
+    idleTimeoutMillis?: number;
+    connectionTimeoutMillis?: number;
+  };
+}
+/**
+ * Apps may augment this registry to type their named connections.
+ */
+interface CustomConnectionRegistry {}
+interface DatabaseConfig {
+  /**
+   * The name of the connection used when none is requested.
+   */
+  default: string;
+  /**
+   * The configured connections, keyed by the name referenced by `default` and
+   * by the model/query APIs.
+   */
+  connections: Record<string, ConnectionConfig> & CustomConnectionRegistry;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Read a value from the `database` configuration namespace with a fallback.
+ *
+ * Never throws when the config file is missing; returns the default instead.
+ *
+ * @param key           Dot path within the database config.
+ * @param defaultValue  Value returned when the key is not set.
+ */
+declare const configure: <T extends DotPath<DatabaseConfig>>(key: T, defaultValue: unknown) => DotPathValue<DatabaseConfig, T>;
+/**
+ * Resolve a configured {@link ConnectionConfig} by name, or the default
+ * connection when none is given.
+ *
+ * @param name  The connection name. Defaults to `database.default`.
+ * @throws when the named connection is not configured.
+ */
+declare const resolveConnection: (name?: string) => ConnectionConfig;
+//#endregion
+//#region src/kysely.d.ts
+/**
+ * Build a pg {@link Pool} from a {@link ConnectionConfig}. A `url` (or
+ * `DATABASE_URL`) wins over the discrete `host`/`port`/`user`/... fields.
+ *
+ * @param connection
+ * @returns
+ */
+declare const createPool: (connection: ConnectionConfig) => Pool;
+/**
+ * Build a Kysely instance for the given connection using the Postgres dialect.
+ *
+ * @param connection
+ * @returns
+ */
+declare const createKysely: <DB = Record<string, never>>(connection: ConnectionConfig) => Kysely<DB>;
+/**
+ * Build an ArkORM Kysely adapter for the given connection. This is what binds
+ * models to the database.
+ *
+ * @param connection
+ * @returns
+ */
+declare const createAdapter: (connection: ConnectionConfig) => _$arkormx.KyselyDatabaseAdapter;
+//#endregion
+//#region src/arkorm.d.ts
+interface DefineArkormConfigOptions extends Partial<ArkormConfig> {
+  /**
+   * The application's database configuration. When provided (and no explicit
+   * `adapter` is set), the adapter is built from the resolved connection.
+   */
+  database?: DatabaseConfig;
+  /**
+   * The connection name to bind. Defaults to `database.default`.
+   */
+  connection?: string;
+}
+/**
+ * Build the ArkORM config object for an application from its database
+ * configuration. Use this only when authoring an explicit `arkormx.config.ts`;
+ * by default the framework configures ArkORM for you (see {@link bootArkorm}).
+ *
+ * @param options  Arkorm config plus the app's database config.
+ */
+declare const defineArkormConfig: (options?: DefineArkormConfigOptions) => ArkormConfig;
+interface BootArkormOptions extends Partial<ArkormConfig> {
+  /** The connection name to bind. Defaults to `database.default`. */
+  connection?: string;
+}
+/**
+ * Configure ArkORM natively from `src/config/database.ts`, so applications work
+ * without an `arkormx.config.ts`.
+ *
+ * Builds the adapter from the default (or named) connection, registers the
+ * conventional paths and the resora pagination resolver, and binds models. A
+ * user-provided `arkormx.config.{ts,js}` always wins — in that case this is a
+ * no-op and ArkORM loads the file instead.
+ *
+ * @param options  Optional overrides merged over the derived config.
+ * @returns        Whether the framework applied its configuration.
+ */
+declare const bootArkorm: (options?: BootArkormOptions) => boolean;
+//#endregion
+export { BootArkormOptions, ConnectionConfig, ConnectionPassword, CustomConnectionRegistry, DB, DatabaseConfig, DefineArkormConfigOptions, Migration, Model, ModelFactory, SchemaBuilder, Seeder, ValidatorDBDriver, bootArkorm, configure, createAdapter, createKysely, createPool, defineArkormConfig, resolveConnection };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { t as ValidatorDBDriver } from "./ValidatorDBDriver-DUvJ-_jF.js";
+import { a as createPool, c as ValidatorDBDriver, i as createKysely, n as defineArkormConfig, o as configure, r as createAdapter, s as resolveConnection, t as bootArkorm } from "./arkorm-BdOIitRp.js";
 import { DB as DB$1, Migration as Migration$1, Model as Model$1, ModelFactory as ModelFactory$1, SchemaBuilder as SchemaBuilder$1, Seeder as Seeder$1 } from "arkormx";
 //#region src/extensions/DB.ts
 var DB = class extends DB$1 {};
@@ -18,4 +18,4 @@ var SchemaBuilder = class extends SchemaBuilder$1 {};
 //#region src/extensions/Seeder.ts
 var Seeder = class extends Seeder$1 {};
 //#endregion
-export { DB, Migration, Model, ModelFactory, SchemaBuilder, Seeder, ValidatorDBDriver };
+export { DB, Migration, Model, ModelFactory, SchemaBuilder, Seeder, ValidatorDBDriver, bootArkorm, configure, createAdapter, createKysely, createPool, defineArkormConfig, resolveConnection };

package/dist/setup.js

@@ -1,9 +1,18 @@
-import { t as ValidatorDBDriver } from "./ValidatorDBDriver-DUvJ-_jF.js";
+import { c as ValidatorDBDriver, t as bootArkorm } from "./arkorm-BdOIitRp.js";
 import { Validator } from "kanun";
+import "dotenv/config";
 import { CoreRouter } from "clear-router/core";
 import { clearRouterPlugin } from "@arkormx/plugin-clear-router";
 //#region src/setup.ts
 CoreRouter.use(clearRouterPlugin);
 Validator.useDatabase(new ValidatorDBDriver());
+/**
+* Configure ArkORM from `src/config/database.ts` so the application works
+* without an `arkormx.config.ts`. A user-provided config file still takes
+* precedence, and an unconfigured database (e.g. some CLI contexts) is ignored.
+*/
+try {
+	bootArkorm();
+} catch {}
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/database",
-  "version": "0.12.36",
+  "version": "0.13.0",
   "type": "module",
   "description": "Database module for Arkstack, providing core database integration and data layer features.",
   "homepage": "https://arkstack.toneflix.net",
@@ -48,10 +48,17 @@
     "clear-router": "^2.8.8"
   },
   "dependencies": {
-    "@arkormx/plugin-clear-router": "^0.1.45",
-    "arkormx": "^2.9.0",
-    "@arkstack/common": "^0.12.36",
-    "@arkstack/contract": "^0.12.36"
+    "@arkormx/plugin-clear-router": "^0.1.46",
+    "dotenv": "^17.4.2",
+    "arkormx": "^2.9.2",
+    "kysely": "^0.28.15",
+    "pg": "^8.20.0",
+    "resora": "^1.3.26",
+    "@arkstack/common": "^0.13.0",
+    "@arkstack/contract": "^0.13.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.16.0"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",

package/dist/ValidatorDBDriver-DUvJ-_jF.js

@@ -1,16 +0,0 @@
-import { DB } from "arkormx";
-import { IDatabaseDriver } from "kanun";
-//#region src/ValidatorDBDriver.ts
-var ValidatorDBDriver = class extends IDatabaseDriver {
-	async exists({ table, column, value, ignore }) {
-		try {
-			const query = DB.table(table).where({ [column]: value });
-			if (ignore) query.whereNot({ [column]: ignore });
-			return await query.exists();
-		} catch {
-			return false;
-		}
-	}
-};
-//#endregion
-export { ValidatorDBDriver as t };