@appweaver/data 0.0.0-stage → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luka Matosevic
+
+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

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://appweaver.co" target="_blank"><img src="https://raw.githubusercontent.com/lmatosevic/appweaver/refs/heads/main/resources/appweaver-logo.svg" width="460" alt="Appweaver Logo" /></a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  The data layer of Appweaver, the AI-first <a href="https://nodejs.org" target="_blank">Node.js</a> framework for backends built with agents.
+</p>
+
+<p align="center">
+<a href="https://www.npmjs.com/package/@appweaver/data" target="_blank"><img src="https://img.shields.io/npm/v/@appweaver/data.svg" alt="NPM Version" /></a>
+<a href="https://github.com/lmatosevic/appweaver/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/npm/l/@appweaver/data.svg" alt="Package License" /></a>
+<a href="https://www.npmjs.com/package/@appweaver/data" target="_blank"><img src="https://img.shields.io/npm/dw/@appweaver/data.svg" alt="NPM Downloads" /></a>
+</p>
+
+## Description
+
+`@appweaver/data` is the database module of [Appweaver](https://github.com/lmatosevic/appweaver), built on
+[Prisma](https://prisma.io):
+
+- **Resources** – `createModel`, `createService` and `createPolicy`, the resource services with filtering, sorting,
+  cursor pagination, aggregation and CSV export, and the transactions.
+- **Auth data model** – `createAuthModel`, `createAuthService`, roles, permissions, API keys, one-time tokens,
+  connected accounts and password hashing.
+- **Files** – `FileService` with the File model, storing the files in any `Storage` provider.
+- **Seeders** – `createSeeder` and the database security store.
+
+The framework models reach only the applications using them: the auth tables with an auth model, File with a model
+declaring `files`, Seeder with a seeders directory.
+
+## Installation
+
+```sh
+npm install @appweaver/data @prisma/client prisma @prisma/adapter-pg  # the driver adapter of your database
+```
+
+The client connects through the Prisma driver adapter of the database: `@prisma/adapter-pg` (PostgreSQL),
+`@prisma/adapter-mariadb` (MySQL / MariaDB), `@prisma/adapter-better-sqlite3` (SQLite, `@prisma/adapter-libsql` on Bun)
+or `@prisma/adapter-mssql` (SQL Server). `prisma` is a dependency, since `weaver migrate` runs it in production.
+
+```ts
+// src/resources/post/model.ts
+import { createModel } from '@appweaver/data';
+
+export default createModel({
+  name: 'Post',
+  scalars: {
+    title: { type: 'string', minLength: 1, maxLength: 200 },
+    body: { type: 'string' }
+  }
+});
+```
+
+Run `weaver generate` after changing a model to refresh the generated types and the Prisma schema.
+
+## Documentation
+
+- [Appweaver README](https://github.com/lmatosevic/appweaver#readme) – getting started, configuration, and the overview of every package
+- [Agent skill](https://github.com/lmatosevic/appweaver/blob/main/skill/SKILL.md) – the complete framework reference shipped to every scaffolded project
+
+## License
+
+Appweaver is [MIT licensed](LICENSE).

package/config.d.ts

@@ -0,0 +1,6 @@
+/** The config sections of data, importable without loading Prisma, i.e. by the CLI and `prisma.config.ts`. */
+export * from './database/database-config';
+export * from './export/export-config';
+export * from './resource/resource-config';
+export * from './security/auth-config';
+export * from './storage/image-config';

package/config.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/** The config sections of data, importable without loading Prisma, i.e. by the CLI and `prisma.config.ts`. */
+__exportStar(require("./database/database-config"), exports);
+__exportStar(require("./export/export-config"), exports);
+__exportStar(require("./resource/resource-config"), exports);
+__exportStar(require("./security/auth-config"), exports);
+__exportStar(require("./storage/image-config"), exports);

package/database/create-client.d.ts

@@ -0,0 +1,11 @@
+import { PrismaClient } from '../prisma/client/client';
+/**
+ * Creates and returns a PrismaClient instance based on the configured database type.
+ *
+ * The database type is determined by the `DATABASE_TYPE` configuration value or,
+ * if unspecified, by parsing the `DATABASE_URL` configuration.
+ * Supported database types include SQLite, PostgreSQL, and MySQL.
+ *
+ * @return {PrismaClient} A PrismaClient instance configured for the selected database type.
+ */
+export declare function createClient(): PrismaClient;

package/database/create-client.js

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+const node_path_1 = __importDefault(require("node:path"));
+const common_1 = require("@appweaver/common");
+const database_config_1 = require("./database-config");
+const options = {
+    transactionOptions: {
+        maxWait: database_config_1.databaseConfig.TRANSACTION_MAX_WAIT,
+        timeout: database_config_1.databaseConfig.TRANSACTION_TIMEOUT
+    },
+    log: database_config_1.databaseConfig.LOG_EVENTS.map((e) => ({ emit: 'event', level: e }))
+};
+/**
+ * Creates and returns a PrismaClient instance based on the configured database type.
+ *
+ * The database type is determined by the `DATABASE_TYPE` configuration value or,
+ * if unspecified, by parsing the `DATABASE_URL` configuration.
+ * Supported database types include SQLite, PostgreSQL, and MySQL.
+ *
+ * @return {PrismaClient} A PrismaClient instance configured for the selected database type.
+ */
+function createClient() {
+    const dbType = (0, common_1.resolveDatabaseType)(database_config_1.databaseConfig.TYPE, database_config_1.databaseConfig.URL);
+    switch (dbType) {
+        case common_1.DatabaseType.Sqlite:
+            return sqliteClient();
+        case common_1.DatabaseType.PostgreSQL:
+            return postgresClient();
+        case common_1.DatabaseType.MySQL:
+            return mysqlClient();
+        case common_1.DatabaseType.SQLServer:
+            return sqlServerClient();
+        default:
+            return sqliteClient();
+    }
+}
+/**
+ * Initializes and returns an instance of the PrismaClient configured with a Better SQLite3 adapter.
+ *
+ * This method sets up a database connection using the PrismaBetterSqlite3 adapter with the provided
+ * database URL and additional options.
+ *
+ * @return {PrismaClient} A configured instance of PrismaClient for interacting with the SQLite database.
+ */
+function sqliteClient() {
+    let sqliteAdapter;
+    if (common_1.appConfig.RUNTIME === common_1.Runtime.Bun) {
+        const { PrismaLibSql } = (0, common_1.requireModule)('@prisma/adapter-libsql', true).value;
+        sqliteAdapter = PrismaLibSql;
+    }
+    else {
+        const { PrismaBetterSqlite3 } = (0, common_1.requireModule)('@prisma/adapter-better-sqlite3', true).value;
+        sqliteAdapter = PrismaBetterSqlite3;
+    }
+    const adapter = new sqliteAdapter({
+        url: database_config_1.databaseConfig.URL || 'file:./sqlite.db'
+    });
+    return createPrismaClient(adapter);
+}
+/**
+ * Creates and returns an instance of PrismaClient configured with the specified options.
+ * The `schema` parameter of the database URL selects the PostgreSQL schema, `public` by default.
+ *
+ * @return {PrismaClient} An instance of PrismaClient used to interact with a PostgreSQL database.
+ */
+function postgresClient() {
+    const { PrismaPg } = (0, common_1.requireModule)('@prisma/adapter-pg', true).value;
+    // Prisma Migrate reads the schema from the URL, while the adapter ignores it
+    // and would query the "public" schema, so pass it on
+    const schema = new URL(database_config_1.databaseConfig.URL).searchParams.get('schema') ?? undefined;
+    const adapter = new PrismaPg({ connectionString: database_config_1.databaseConfig.URL }, { schema });
+    return createPrismaClient(adapter);
+}
+/**
+ * Initializes and returns an instance of PrismaClient configured to use
+ * a MariaDB adapter with the specified database connection settings.
+ *
+ * @return {PrismaClient} A PrismaClient instance configured for MariaDB.
+ */
+function mysqlClient() {
+    const { PrismaMariaDb } = (0, common_1.requireModule)('@prisma/adapter-mariadb', true).value;
+    const dbUrl = new URL(database_config_1.databaseConfig.URL);
+    const adapter = new PrismaMariaDb({
+        host: dbUrl.hostname,
+        port: parseInt(dbUrl.port || '3306', 10),
+        user: decodeURIComponent(dbUrl.username),
+        password: decodeURIComponent(dbUrl.password),
+        database: dbUrl.pathname.slice(1)
+    });
+    return createPrismaClient(adapter);
+}
+/**
+ * Creates and returns a PrismaClient configured to connect to a SQL Server database.
+ *
+ * This method uses the Prisma MSSQL adapter with the connection string from config.
+ *
+ * @return {PrismaClient} An instance of PrismaClient for interacting with the SQL Server database.
+ */
+function sqlServerClient() {
+    const { PrismaMssql } = (0, common_1.requireModule)('@prisma/adapter-mssql', true).value;
+    const adapter = new PrismaMssql(database_config_1.databaseConfig.URL);
+    return createPrismaClient(adapter);
+}
+/**
+ * Creates and returns an instance of PrismaClient configured with the specified SQL driver adapter.
+ * The PrismaClient class is loaded from the configured output path relative to the root directory.
+ *
+ * @param {SqlDriverAdapterFactory} adapter - The SQL driver adapter factory used to configure the PrismaClient.
+ * @return {PrismaClient} A configured PrismaClient instance.
+ */
+function createPrismaClient(adapter) {
+    const cwd = process.cwd();
+    const mainPath = require.main?.filename || process.argv[1];
+    const relativeMainPath = mainPath.replace(`${cwd}${node_path_1.default.sep}`, '');
+    const distDirName = relativeMainPath.includes('node_modules')
+        ? 'dist'
+        : relativeMainPath.split(node_path_1.default.sep)[0];
+    const buildDirPath = (0, common_1.isTypeScriptRuntime)()
+        ? ''
+        : common_1.appConfig.BUILD_PATH || distDirName;
+    const testDirPath = !(0, common_1.isTypeScriptRuntime)() && common_1.appConfig.ENV === 'test' ? '..' : '';
+    // Construct the Prisma client path supporting multiple different ways of running
+    // application (JavaScript runtime, TypeScript runtime, tests, from CLI, ...)
+    const clientPath = node_path_1.default.join(cwd, buildDirPath, testDirPath, database_config_1.databaseConfig.CLIENT_OUTPUT_DIR_PATH, 'client');
+    const { PrismaClient } = (0, common_1.requireModule)(clientPath, true).value;
+    const client = new PrismaClient({ adapter, ...options });
+    // Add configured Prisma event logging
+    for (const event of database_config_1.databaseConfig.LOG_EVENTS) {
+        if (event === common_1.DatabaseEvent.Query) {
+            client.$on(event, (e) => {
+                common_1.logger.debug(e, 'Prisma query');
+            });
+        }
+        else {
+            client.$on(event, (e) => {
+                common_1.logger[event](e, `Prisma ${event} log`);
+            });
+        }
+    }
+    return client;
+}

package/database/database-config.d.ts

@@ -0,0 +1,14 @@
+import { DatabaseEvent, DatabaseType } from '@appweaver/common';
+export declare const databaseConfig: Readonly<{
+    TYPE?: DatabaseType | undefined;
+    URL: string;
+    SCHEMA_PATH: string;
+    MIGRATIONS_DIR_PATH: string;
+    SEEDERS_DIR_PATH: string;
+    CLIENT_OUTPUT_DIR_PATH: string;
+    TRANSACTION_MAX_WAIT: number;
+    TRANSACTION_TIMEOUT: number;
+    AI_DANGEROUS_ACTIONS_ENABLED: boolean;
+    LOG_EVENTS: DatabaseEvent[];
+    PROVIDER: string;
+}>;

package/database/database-config.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.databaseConfig = void 0;
+const typebox_1 = require("@sinclair/typebox");
+const common_1 = require("@appweaver/common");
+exports.databaseConfig = (0, common_1.defineConfig)('database', {
+    /** Database type. Values: `sqlite`, `postgresql`, `mysql`, `sqlserver`. */
+    TYPE: typebox_1.Type.Optional(typebox_1.Type.Enum(common_1.DatabaseType)),
+    /** Database connection URL/DSN. Default: `''`. */
+    URL: typebox_1.Type.String({ default: '' }),
+    /** Path to a Prisma schema file. Default: `'./database/schema.prisma'`. */
+    SCHEMA_PATH: typebox_1.Type.String({
+        default: './database/schema.prisma'
+    }),
+    /** Path to the database migrations directory. Default: `'./database/migrations'`. */
+    MIGRATIONS_DIR_PATH: typebox_1.Type.String({
+        default: './database/migrations'
+    }),
+    /** Path to the database seeders directory. Default: `'./database/seeders'`. */
+    SEEDERS_DIR_PATH: typebox_1.Type.String({
+        default: './database/seeders'
+    }),
+    /** Path for generated Prisma client output. Default: `'./database/client'`. */
+    CLIENT_OUTPUT_DIR_PATH: typebox_1.Type.String({
+        default: './database/client'
+    }),
+    /** Max wait time for acquiring a transaction lock in milliseconds. Default: `2000` (2 sec). */
+    TRANSACTION_MAX_WAIT: typebox_1.Type.Integer({ default: 2000 }),
+    /** Transaction timeout in milliseconds. Default: `5000` (5 sec). */
+    TRANSACTION_TIMEOUT: typebox_1.Type.Integer({ default: 5000 }),
+    /** Allow an AI agent to run dangerous Prisma actions, such as a database reset. Disable it in production.
+     * Default: `true`. */
+    AI_DANGEROUS_ACTIONS_ENABLED: typebox_1.Type.Boolean({ default: true }),
+    /** Array of database events to log. Values: `query`, `info`, `warn`, `error`. Default: `[]`. */
+    LOG_EVENTS: typebox_1.Type.Array(typebox_1.Type.Enum(common_1.DatabaseEvent), {
+        default: []
+    }),
+    /** Database provider: `auto` or `prisma`, or `none` for an application without a database. Default: `'auto'`. */
+    PROVIDER: typebox_1.Type.String({ default: 'auto' })
+});

package/database/database-error.d.ts

@@ -0,0 +1,49 @@
+/** The constraint a driver adapter reports as violated. */
+type AdapterConstraint = {
+    fields: string[];
+} | {
+    index: string;
+} | {
+    foreignKey: Record<string, unknown>;
+};
+type PrismaError = Error & {
+    code?: string;
+    errorCode?: string;
+    meta?: {
+        modelName?: string;
+        target?: string | string[];
+        column_name?: string;
+        field_name?: string;
+        driverAdapterError?: {
+            cause?: {
+                kind?: string;
+                constraint?: AdapterConstraint;
+                column?: string;
+            };
+        };
+    };
+};
+/**
+ * Checks whether an error was raised by the Prisma client.
+ */
+export declare function isPrismaError(error: unknown): error is PrismaError;
+/**
+ * Translates an error of the Prisma client into a {@link DatabaseError}
+ * describing what failed, i.e. which fields violate a unique constraint. Any
+ * other error, i.e. an {@link AppweaverError} or a bug of the code the
+ * operation runs, is returned as it is.
+ *
+ * @param {unknown} error The error the operation failed with.
+ * @param {string} [model] The name of the model the operation ran on, used when
+ * the error does not name one.
+ * @return {unknown} The translated error keeping the Prisma error as its
+ * cause, or the error as it is.
+ */
+export declare function toDatabaseError(error: unknown, model?: string): unknown;
+/**
+ * Returns the explanation of a Prisma error, without the invocation and the
+ * code frame its message starts with, i.e. "Unique constraint failed on the
+ * fields: (`email`)".
+ */
+export declare function prismaErrorMessage(error: Error): string;
+export {};

package/database/database-error.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrismaError = isPrismaError;
+exports.toDatabaseError = toDatabaseError;
+exports.prismaErrorMessage = prismaErrorMessage;
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+/** The error codes of the error kinds a driver adapter reports. */
+const ADAPTER_KINDS = {
+    UniqueConstraintViolation: common_1.ErrorCode.DatabaseUniqueViolation,
+    ForeignKeyConstraintViolation: common_1.ErrorCode.DatabaseForeignKeyViolation,
+    NullConstraintViolation: common_1.ErrorCode.DatabaseNullViolation,
+    LengthMismatch: common_1.ErrorCode.DatabaseValueTooLong,
+    ValueOutOfRange: common_1.ErrorCode.DatabaseValueOutOfRange,
+    InvalidInputValue: common_1.ErrorCode.DatabaseInvalidValue,
+    InconsistentColumnData: common_1.ErrorCode.DatabaseInvalidValue,
+    TransactionWriteConflict: common_1.ErrorCode.DatabaseWriteConflict
+};
+/** The error codes of the Prisma error codes. */
+const PRISMA_CODES = {
+    P2000: common_1.ErrorCode.DatabaseValueTooLong,
+    P2002: common_1.ErrorCode.DatabaseUniqueViolation,
+    P2003: common_1.ErrorCode.DatabaseForeignKeyViolation,
+    P2006: common_1.ErrorCode.DatabaseInvalidValue,
+    P2007: common_1.ErrorCode.DatabaseInvalidValue,
+    P2011: common_1.ErrorCode.DatabaseNullViolation,
+    P2020: common_1.ErrorCode.DatabaseValueOutOfRange,
+    P2023: common_1.ErrorCode.DatabaseInvalidValue,
+    P2025: common_1.ErrorCode.DatabaseRecordNotFound,
+    P2034: common_1.ErrorCode.DatabaseWriteConflict
+};
+// The connection errors, a connection pool timeout and too many connections
+const UNAVAILABLE_CODES = /^P10\d\d$|^P2024$|^P2037$/;
+/**
+ * Checks whether an error was raised by the Prisma client.
+ */
+function isPrismaError(error) {
+    return (error instanceof Error &&
+        (error.name.startsWith('PrismaClient') ||
+            /^P\d{4}$/.test(String(error.code))));
+}
+/**
+ * Translates an error of the Prisma client into a {@link DatabaseError}
+ * describing what failed, i.e. which fields violate a unique constraint. Any
+ * other error, i.e. an {@link AppweaverError} or a bug of the code the
+ * operation runs, is returned as it is.
+ *
+ * @param {unknown} error The error the operation failed with.
+ * @param {string} [model] The name of the model the operation ran on, used when
+ * the error does not name one.
+ * @return {unknown} The translated error keeping the Prisma error as its
+ * cause, or the error as it is.
+ */
+function toDatabaseError(error, model) {
+    if ((0, common_1.isAppweaverError)(error) || !isPrismaError(error)) {
+        return error;
+    }
+    const options = { cause: error };
+    const prismaCode = error.code ?? error.errorCode;
+    const modelName = error.meta?.modelName ?? model;
+    const cause = error.meta?.driverAdapterError?.cause;
+    const code = (cause?.kind ? ADAPTER_KINDS[cause.kind] : undefined) ??
+        (prismaCode ? PRISMA_CODES[prismaCode] : undefined) ??
+        validationErrorCode(error);
+    if (!code) {
+        if (prismaCode && UNAVAILABLE_CODES.test(prismaCode)) {
+            return new common_1.DatabaseError(common_1.ErrorCode.DatabaseUnavailable, 'Database is unavailable', {}, options);
+        }
+        return new common_1.DatabaseError(common_1.ErrorCode.DatabaseOperationFailed, `${modelName ?? 'Database'} operation failed`, { model: modelName, prismaCode }, options);
+    }
+    const subject = modelName ?? 'Record';
+    switch (code) {
+        case common_1.ErrorCode.DatabaseRecordNotFound:
+            return new common_1.DatabaseError(code, `${subject} not found`, { model: modelName }, options);
+        case common_1.ErrorCode.DatabaseWriteConflict:
+            return new common_1.DatabaseError(code, `${subject} was changed by a concurrent operation, retry the operation`, { model: modelName }, options);
+    }
+    const constraint = cause?.constraint;
+    const fields = violatedFields(error, modelName, cause?.column);
+    const details = {
+        model: modelName,
+        fields,
+        ...(constraint && 'index' in constraint
+            ? { constraint: constraint.index }
+            : {})
+    };
+    return new common_1.DatabaseError(code, violationMessage(code, subject, fields), details, options);
+}
+/**
+ * Returns the explanation of a Prisma error, without the invocation and the
+ * code frame its message starts with, i.e. "Unique constraint failed on the
+ * fields: (`email`)".
+ */
+function prismaErrorMessage(error) {
+    const lines = error.message
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return lines[lines.length - 1] ?? error.name;
+}
+/** The violations the Prisma client reports before reaching the database. */
+function validationErrorCode(error) {
+    if (error.name !== 'PrismaClientValidationError') {
+        return undefined;
+    }
+    return /Argument `\w+` is missing/.test(error.message)
+        ? common_1.ErrorCode.DatabaseNullViolation
+        : undefined;
+}
+/** Returns the model fields an error reports as violated, normalized from the
+ * columns the database reports. */
+function violatedFields(error, modelName, column) {
+    const model = modelName ? (0, core_1.injectModel)(modelName, false) : undefined;
+    return reportedColumns(error, column, model).map((name) => modelField(unquote(name), model));
+}
+/** Returns the columns an error reports as violated, the ones of a named index
+ * resolved from the constraints of its model. */
+function reportedColumns(error, column, model) {
+    const constraint = error.meta?.driverAdapterError?.cause?.constraint;
+    if (constraint && 'fields' in constraint) {
+        return constraint.fields;
+    }
+    if (constraint && 'index' in constraint) {
+        return indexColumns(constraint.index, model);
+    }
+    if (column) {
+        return [column];
+    }
+    const target = error.meta?.target;
+    if (Array.isArray(target)) {
+        return target;
+    }
+    if (typeof target === 'string') {
+        return indexColumns(target, model);
+    }
+    const missing = error.message.match(/Argument `(\w+)` is missing/);
+    if (missing) {
+        return [missing[1]];
+    }
+    const field = error.meta?.field_name ?? error.meta?.column_name;
+    return field ? [field] : [];
+}
+/**
+ * Returns the model field a column holds: the relation of a foreign key
+ * column, i.e. `author` for `authorId`, and the column itself otherwise. A
+ * column reported with its table, i.e. `Post.title`, is stripped of it.
+ */
+function modelField(column, model) {
+    const name = column.slice(column.lastIndexOf('.') + 1);
+    const relation = name.endsWith('Id') ? name.slice(0, -2) : undefined;
+    return relation && model?.config.relations?.[relation] ? relation : name;
+}
+/**
+ * Resolves the columns of a named index from the constraints of its model,
+ * following the default Prisma naming of `<Table>_<columns>_key` for a unique
+ * constraint and `<Table>_<column>_fkey` for a foreign key.
+ */
+function indexColumns(index, model) {
+    if (!model) {
+        return [];
+    }
+    const table = model.config.tableName ?? model.name;
+    const candidates = [
+        ...(model.config.unique ?? []).map((entry) => (Array.isArray(entry) ? entry : [entry]).map(stripOrder)),
+        ...Object.entries(model.config.scalars ?? {})
+            .filter(([, scalar]) => scalar.unique)
+            .map(([name]) => [name]),
+        ...Object.keys(model.config.relations ?? {}).map((name) => [`${name}Id`])
+    ];
+    return (candidates.find((columns) => ['key', 'fkey'].some((suffix) => index === `${table}_${columns.join('_')}_${suffix}`)) ?? []);
+}
+function violationMessage(code, subject, fields) {
+    const quoted = fields.map((field) => `'${field}'`).join(', ');
+    const plural = fields.length > 1;
+    switch (code) {
+        case common_1.ErrorCode.DatabaseUniqueViolation:
+            return fields.length > 0
+                ? `${subject} with the same ${fields.join(' and ')} already exists`
+                : `${subject} violates a unique constraint`;
+        case common_1.ErrorCode.DatabaseNullViolation:
+            return fields.length > 0
+                ? `${subject} field${plural ? 's' : ''} ${quoted} ${plural ? 'are' : 'is'} required`
+                : `${subject} is missing a required field`;
+        case common_1.ErrorCode.DatabaseValueTooLong:
+            return fields.length > 0
+                ? `${subject} field ${quoted} value is too long`
+                : `${subject} field value is too long`;
+        case common_1.ErrorCode.DatabaseValueOutOfRange:
+            return fields.length > 0
+                ? `${subject} field ${quoted} value is out of range`
+                : `${subject} field value is out of range`;
+        case common_1.ErrorCode.DatabaseForeignKeyViolation:
+            return fields.length > 0
+                ? `${subject} relation ${quoted} references a missing record, or is still referenced by another record`
+                : `${subject} violates a relation constraint`;
+        default:
+            return fields.length > 0
+                ? `${subject} field ${quoted} value is invalid`
+                : `${subject} field value is invalid`;
+    }
+}
+function unquote(name) {
+    return name.replace(/^[`"[]|[`"\]]$/g, '');
+}
+function stripOrder(field) {
+    return field.replace(/^[-+]/, '');
+}
+// The Prisma errors reach the API as a DatabaseError naming the violated
+// constraint, with the message of Prisma only when the server enables it
+(0, common_1.defineErrorTranslator)({
+    name: 'database',
+    matches: isPrismaError,
+    translate: (error) => toDatabaseError(error),
+    describe: (error) => prismaErrorMessage(error),
+    exposeDescription: () => common_1.config.bool('SERVER_ERROR_DATABASE_MESSAGE_ENABLED', false)
+});

package/database/index.d.ts

@@ -0,0 +1,3 @@
+export * from './database-error';
+export * from './prisma-database';
+export * from './run-transaction';

package/database/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./database-error"), exports);
+__exportStar(require("./prisma-database"), exports);
+__exportStar(require("./run-transaction"), exports);

package/database/prisma-database.d.ts

@@ -0,0 +1,33 @@
+import { Database, HealthCheckResult, TransactionOptions } from '@appweaver/common';
+import { PrismaClient } from '../prisma/client/client';
+/**
+ * Represents a database utility class that provides methods
+ * to connect to and disconnect from the database, as well as
+ * access to the database Prisma client instance.
+ */
+export declare class PrismaDatabase extends Database {
+    /**
+     * Connects to the database and checks the connection, logging an error when the database is unreachable instead of
+     * failing the start, since most drivers connect lazily and the queries reconnect once it is reachable.
+     */
+    onInit(): Promise<void>;
+    onDestroy(): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Returns the Prisma client, which runs its queries in the transaction the
+     * current call runs in (see `runTransaction`), and on the connection otherwise.
+     */
+    client<T = PrismaClient>(): T;
+    checkHealth(): Promise<HealthCheckResult>;
+    /**
+     * Runs the given function in a transaction, or in the current one when called
+     * inside a transaction already. See `runTransaction`.
+     *
+     * @param {Function} fn - The function to run, receiving the transaction client.
+     * @param {TransactionOptions} [options] - The transaction options.
+     * @return {Promise<Object>} The value returned by the function.
+     * @throws The error thrown by the function, after the transaction rolled back.
+     */
+    transaction<T>(fn: (tx: any) => Promise<T>, options?: TransactionOptions): Promise<T>;
+}