@devxcrew/framework 0.1.10 → 0.1.12

package/dist/modules/database/drivers/sqlite/sqlite.connection.d.ts

@@ -0,0 +1,13 @@
+import { SqliteDialect, type SqliteDatabase } from "kysely";
+export declare function createSqliteDialect(path: string): SqliteDialect;
+export declare class NodeSqliteDatabase implements SqliteDatabase {
+    private readonly database;
+    constructor(path: string);
+    prepare(query: string): {
+        reader: boolean;
+        all: (parameters: readonly unknown[]) => Record<string, import("node:sqlite").SQLOutputValue>[];
+        run: (parameters: readonly unknown[]) => import("node:sqlite").StatementResultingChanges;
+        iterate: (parameters: readonly unknown[]) => NodeJS.Iterator<Record<string, import("node:sqlite").SQLOutputValue>, undefined, any>;
+    };
+    close(): void;
+}

package/dist/modules/database/drivers/sqlite/sqlite.connection.js

@@ -0,0 +1,41 @@
+import { DatabaseSync } from "node:sqlite";
+import { SqliteDialect } from "kysely";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+export function createSqliteDialect(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    return new SqliteDialect({
+        database: async () => new NodeSqliteDatabase(path),
+    });
+}
+export class NodeSqliteDatabase {
+    database;
+    constructor(path) {
+        this.database = new DatabaseSync(path);
+        this.database.exec("PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL;");
+    }
+    prepare(query) {
+        const statement = this.database.prepare(query);
+        statement.setReadBigInts(true);
+        return {
+            reader: statement.columns().length > 0,
+            all: (parameters) => statement.all(...bind(parameters)),
+            run: (parameters) => statement.run(...bind(parameters)),
+            iterate: (parameters) => statement.iterate(...bind(parameters)),
+        };
+    }
+    close() {
+        this.database.close();
+    }
+}
+function bind(parameters) {
+    return parameters.map((value) => {
+        if (value === null ||
+            typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "bigint" ||
+            value instanceof Uint8Array)
+            return value;
+        throw new TypeError("Unsupported SQLite parameter type.");
+    });
+}

package/dist/modules/database/drivers/sqlite/sqlite.schema.d.ts

@@ -0,0 +1,3 @@
+export declare function sqliteConfig(environment: NodeJS.ProcessEnv): {
+    path: string;
+};

package/dist/modules/database/drivers/sqlite/sqlite.schema.js

@@ -0,0 +1,9 @@
+import { resolve } from "node:path";
+export function sqliteConfig(environment) {
+    const path = environment.DB_SQLITE_PATH ?? "storage/private/data/identity.sqlite";
+    if (!path.trim())
+        throw new Error("DB_SQLITE_PATH must not be empty.");
+    if (path === ":memory:" || path.startsWith("file:"))
+        throw new Error("DB_SQLITE_PATH must identify a persisted SQLite file.");
+    return { path: resolve(path) };
+}

package/dist/modules/database/index.d.ts

@@ -0,0 +1,12 @@
+export { createDatabaseProvider, type DatabaseProvider, } from "./database.provider.js";
+export { DatabaseExecution, DatabaseValidationError, } from "./database.execution.js";
+export { ResumableTransfer } from "./database.transfer.js";
+export { DatabaseCapacityError } from "./database.connections.js";
+export { createDatabaseMigrator, prepareMigrationStorage, databaseMetadataMigration, transferCheckpointsMigration, storageMigrations, } from "./database.migration.js";
+export { readDatabaseConfiguration, databaseCommandSchema, } from "./common/index.js";
+export type { DatabaseSchema, DatabaseInfrastructureSchema, DatabaseProviderOptions, ConnectionTarget, } from "./common/database.types.js";
+export { smokeDatabase } from "./database.service.js";
+export { backupConnection, checkConnectionBackup, } from "./operations/database.backup.js";
+export { SqliteDataTransfer } from "./operations/sqlite-import.js";
+export { createDatabaseBackup, verifyDatabaseBackup, } from "./drivers/sqlite/index.js";
+export { createMariaDbBackup, verifyMariaDbBackup, rehearseMariaDbRestore, } from "./drivers/mariadb/index.js";

package/dist/modules/database/index.js

@@ -0,0 +1,11 @@
+export { createDatabaseProvider, } from "./database.provider.js";
+export { DatabaseExecution, DatabaseValidationError, } from "./database.execution.js";
+export { ResumableTransfer } from "./database.transfer.js";
+export { DatabaseCapacityError } from "./database.connections.js";
+export { createDatabaseMigrator, prepareMigrationStorage, databaseMetadataMigration, transferCheckpointsMigration, storageMigrations, } from "./database.migration.js";
+export { readDatabaseConfiguration, databaseCommandSchema, } from "./common/index.js";
+export { smokeDatabase } from "./database.service.js";
+export { backupConnection, checkConnectionBackup, } from "./operations/database.backup.js";
+export { SqliteDataTransfer } from "./operations/sqlite-import.js";
+export { createDatabaseBackup, verifyDatabaseBackup, } from "./drivers/sqlite/index.js";
+export { createMariaDbBackup, verifyMariaDbBackup, rehearseMariaDbRestore, } from "./drivers/mariadb/index.js";

package/dist/modules/database/operations/database.backup.d.ts

@@ -0,0 +1,3 @@
+import { type ConnectionTarget } from "../common/index.js";
+export declare function backupConnection(environment: NodeJS.ProcessEnv, input: ConnectionTarget, path: string): Promise<void>;
+export declare function checkConnectionBackup(environment: NodeJS.ProcessEnv, input: ConnectionTarget, path: string, restore?: boolean): Promise<void>;

package/dist/modules/database/operations/database.backup.js

@@ -0,0 +1,24 @@
+import { createMariaDbBackup, verifyMariaDbBackup, rehearseMariaDbRestore, } from "../drivers/mariadb/index.js";
+import { createDatabaseBackup, verifyDatabaseBackup, } from "../drivers/sqlite/index.js";
+import { connectionTargetSchema, } from "../common/index.js";
+export async function backupConnection(environment, input, path) {
+    const target = connectionTargetSchema.parse(input);
+    if (target.driver === "mariadb")
+        await createMariaDbBackup({ ...environment, DB_MASTER_NAME: target.databaseName }, path);
+    else
+        await createDatabaseBackup(target.sqlitePath, path);
+}
+export async function checkConnectionBackup(environment, input, path, restore = false) {
+    const target = connectionTargetSchema.parse(input);
+    if (target.driver === "mariadb") {
+        if (restore)
+            await rehearseMariaDbRestore({ ...environment, DB_MASTER_NAME: target.databaseName }, path);
+        else
+            await verifyMariaDbBackup(path);
+    }
+    else {
+        if (restore)
+            throw new Error("SQLite backups are verified directly as restored snapshots.");
+        verifyDatabaseBackup(path);
+    }
+}

package/dist/modules/database/operations/sqlite-import.d.ts

@@ -0,0 +1,8 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Kysely } from "kysely";
+export declare class SqliteDataTransfer {
+    private readonly source;
+    private readonly allowed;
+    constructor(source: DatabaseSync, allowed: readonly string[]);
+    execute<Schema>(target: Kysely<Schema>, signal?: AbortSignal): Promise<Record<string, number>>;
+}

package/dist/modules/database/operations/sqlite-import.js

@@ -0,0 +1,96 @@
+import { sql } from "kysely";
+export class SqliteDataTransfer {
+    source;
+    allowed;
+    constructor(source, allowed) {
+        this.source = source;
+        this.allowed = allowed;
+    }
+    async execute(target, signal) {
+        if (this.source.prepare("PRAGMA integrity_check").get()?.integrity_check !==
+            "ok")
+            throw new Error("SQLite integrity failed.");
+        if (this.source.prepare("PRAGMA foreign_key_check").all().length)
+            throw new Error("SQLite foreign keys failed.");
+        this.source.exec("BEGIN");
+        try {
+            const existing = new Set(this.source
+                .prepare("SELECT name FROM sqlite_master WHERE type='table'")
+                .all()
+                .map((row) => String(row.name)));
+            const remaining = new Set(this.allowed.filter((name) => existing.has(name)));
+            const targetTables = new Set((await target.introspection.getTables()).map((table) => table.name));
+            const ordered = [];
+            while (remaining.size) {
+                const ready = [...remaining].filter((table) => {
+                    assertIdentifier(table);
+                    return this.source
+                        .prepare(`PRAGMA foreign_key_list("${table}")`)
+                        .all()
+                        .every((fk) => !remaining.has(String(fk.table)) || fk.table === table);
+                });
+                if (!ready.length)
+                    throw new Error("Cyclic source table dependencies.");
+                for (const table of ready) {
+                    if (!targetTables.has(table))
+                        throw new Error("Destination schema is incomplete.");
+                    remaining.delete(table);
+                    ordered.push(table);
+                }
+            }
+            return await target.transaction().execute(async (transaction) => {
+                const report = {};
+                for (const table of ordered) {
+                    const primary = this.source
+                        .prepare(`PRAGMA table_info("${table}")`)
+                        .all()
+                        .filter((column) => Number(column.pk) > 0)
+                        .map((column) => String(column.name));
+                    if (!primary.length)
+                        throw new Error("Transfer tables require a primary key.");
+                    const statement = this.source.prepare(`SELECT * FROM "${table}"`);
+                    statement.setReadBigInts(true);
+                    let count = 0;
+                    for (const row of statement.iterate()) {
+                        signal?.throwIfAborted();
+                        const columns = Object.keys(row);
+                        columns.forEach(assertIdentifier);
+                        const values = columns.map((key) => typeof row[key] === "bigint" ? String(row[key]) : row[key]);
+                        await sql `INSERT INTO ${sql.table(table)} (${sql.join(columns.map((column) => sql.ref(column)))}) VALUES (${sql.join(values.map((value) => sql `${value}`))})
+ ON DUPLICATE KEY UPDATE ${sql.join(columns.map((column) => sql `${sql.ref(column)}=VALUES(${sql.ref(column)})`))}`.execute(transaction);
+                        const found = await sql `SELECT * FROM ${sql.table(table)} WHERE ${sql.join(primary.map((key) => sql `${sql.ref(key)}=${typeof row[key] === "bigint" ? String(row[key]) : row[key]}`), sql ` AND `)}`.execute(transaction);
+                        if (found.rows.length !== 1 ||
+                            canonical(row) !== canonical(found.rows[0]))
+                            throw new Error(`Import verification failed for ${table}.`);
+                        count++;
+                    }
+                    const total = await sql `SELECT COUNT(*) AS total FROM ${sql.table(table)}`.execute(transaction);
+                    if (BigInt(total.rows[0].total) !== BigInt(count))
+                        throw new Error(`Destination records differ for ${table}.`);
+                    report[table] = count;
+                }
+                signal?.throwIfAborted();
+                return report;
+            });
+        }
+        finally {
+            this.source.exec("ROLLBACK");
+        }
+    }
+}
+function assertIdentifier(name) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
+        throw new Error("Invalid transfer identifier.");
+}
+function canonical(row) {
+    return JSON.stringify(Object.keys(row)
+        .sort()
+        .map((key) => [
+        key,
+        row[key] === null
+            ? null
+            : row[key] instanceof Uint8Array
+                ? Buffer.from(row[key]).toString("hex")
+                : String(row[key]),
+    ]));
+}

package/dist/modules/settings/index.d.ts

@@ -0,0 +1,2 @@
+export { createSettingsProvider } from "./settings.provider.js";
+export type { SettingsProvider, SettingsOptions } from "./settings.types.js";

package/dist/modules/settings/index.js

@@ -0,0 +1 @@
+export { createSettingsProvider } from "./settings.provider.js";

package/dist/modules/settings/settings.controller.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.controller.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.migration.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.migration.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.provider.d.ts

@@ -0,0 +1,2 @@
+import type { SettingsOptions, SettingsProvider } from "./settings.types.js";
+export declare function createSettingsProvider(options?: SettingsOptions): SettingsProvider;

package/dist/modules/settings/settings.provider.js

@@ -0,0 +1,9 @@
+import { SettingsService } from "./settings.service.js";
+export function createSettingsProvider(options = {}) {
+    const service = new SettingsService(options);
+    return {
+        current: () => service.current(),
+        load: (root, overrides) => service.load(root, overrides),
+        write: (root, patch) => service.write(root, patch),
+    };
+}

package/dist/modules/settings/settings.repository.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.repository.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.routes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.routes.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.schema.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.seed.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.seed.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/settings/settings.service.d.ts

@@ -0,0 +1,13 @@
+import type { SettingsOptions } from "./settings.types.js";
+export declare class SettingsService {
+    private readonly options;
+    private snapshot;
+    private readonly writable;
+    private writes;
+    constructor(options: SettingsOptions);
+    current(): Readonly<NodeJS.ProcessEnv>;
+    load(root?: string, overrides?: NodeJS.ProcessEnv): Readonly<NodeJS.ProcessEnv>;
+    write(root: string, patch: Readonly<NodeJS.ProcessEnv>): Promise<void>;
+    private validate;
+    private persist;
+}

package/dist/modules/settings/settings.service.js

@@ -0,0 +1,93 @@
+import { readFileSync } from "node:fs";
+import { readFile, rename, writeFile, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { parseEnv } from "node:util";
+export class SettingsService {
+    options;
+    snapshot;
+    writable;
+    writes = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.snapshot = Object.freeze({ ...options.defaults });
+        this.writable = new Set(options.writableKeys ?? []);
+    }
+    current() {
+        return this.snapshot;
+    }
+    load(root = process.cwd(), overrides = process.env) {
+        let file = {};
+        try {
+            file = parseEnv(readFileSync(resolve(root, ".env"), "utf8"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const environment = { ...this.options.defaults, ...file, ...overrides };
+        this.validate(environment);
+        // The provider never changes process.env or another application's snapshot.
+        this.snapshot = Object.freeze(environment);
+        return this.snapshot;
+    }
+    write(root, patch) {
+        if (Object.entries(patch).some(([key, value]) => !this.writable.has(key) ||
+            value === undefined ||
+            /[\r\n\0]/.test(value)))
+            return Promise.reject(new Error("The settings update contains unsupported values."));
+        this.validate(patch);
+        const result = this.writes.then(() => this.persist(root, patch));
+        this.writes = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    validate(environment) {
+        if (this.options.schema &&
+            !this.options.schema.safeParse(environment).success)
+            throw new Error("Invalid application settings environment.");
+    }
+    async persist(root, patch) {
+        const path = resolve(root, ".env");
+        let source = "";
+        try {
+            source = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const written = new Set();
+        const lines = source.split(/\r?\n/).map((line) => {
+            const key = /^(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/.exec(line)?.[1];
+            if (!key || !Object.hasOwn(patch, key))
+                return line;
+            if (written.has(key))
+                return "";
+            written.add(key);
+            return `${key}=${encodeValue(patch[key])}`;
+        });
+        for (const [key, value] of Object.entries(patch))
+            if (!written.has(key))
+                lines.push(`${key}=${encodeValue(value)}`);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, `${lines.join("\n").replace(/\n+$/, "")}\n`, {
+                mode: 0o600,
+                flag: "wx",
+            });
+            await rename(temporary, path);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+}
+function encodeValue(value) {
+    // Node's .env parser preserves backslashes literally; choose a quote it can read.
+    if (!/[\s#"'`]/.test(value))
+        return value;
+    const quote = ['"', "'"].find((candidate) => !value.includes(candidate));
+    if (!quote)
+        throw new Error("The settings value cannot be represented in an environment file.");
+    return `${quote}${value}${quote}`;
+}

package/dist/modules/settings/settings.types.d.ts

@@ -0,0 +1,11 @@
+import type { z } from "zod";
+export interface SettingsOptions {
+    defaults?: Readonly<NodeJS.ProcessEnv>;
+    schema?: z.ZodType;
+    writableKeys?: readonly string[];
+}
+export interface SettingsProvider {
+    current(): Readonly<NodeJS.ProcessEnv>;
+    load(root?: string, overrides?: NodeJS.ProcessEnv): Readonly<NodeJS.ProcessEnv>;
+    write(root: string, patch: Readonly<NodeJS.ProcessEnv>): Promise<void>;
+}

package/dist/modules/settings/settings.types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/config.js

@@ -15,8 +15,9 @@ export function readApplicationConfig(env) {
         url.search ||
         url.hash)
         throw new Error("APP_URL must be an HTTP origin without credentials or a path.");
-    if (Number(url.port || (url.protocol === "https:" ? 443 : 80)) !== port)
-        throw new Error("APP_URL must use APP_PORT.");
+    const publicPort = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+    if (mode === "development" && publicPort !== port)
+        throw new Error("APP_URL must use APP_PORT in development.");
     return {
         name,
         port,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devxcrew/framework",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "exports": {
     ".": {
@@ -26,9 +26,12 @@
   "devDependencies": {
     "@devxcrew/tools": "0.1.8",
     "@types/node": "^26.0.0",
+    "tsx": "4.23.15",
     "typescript": "6.0.3"
   },
   "dependencies": {
+    "kysely": "0.29.6",
+    "mysql2": "3.23.4",
     "zod": "4.6.5"
   },
   "scripts": {
@@ -51,7 +54,7 @@
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build",
     "release:check": "npm run check && npm run build && npm pack --dry-run --ignore-scripts",
-    "test": "npm run build && node --test"
+    "test": "npm run build && node --test tests/*.test.mjs src/modules/*/*.test.mjs && tsx --test src/modules/database/tests/*.test.ts src/modules/settings/*.test.ts"
   },
   "publishConfig": {
     "access": "public",