@appweaver/data 0.0.0-stage → 2.0.1

package/database/prisma-database.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrismaDatabase = void 0;
+const common_1 = require("@appweaver/common");
+const database_config_1 = require("./database-config");
+const create_client_1 = require("./create-client");
+const internal_1 = require("@appweaver/core/internal");
+// Members that act on the connection itself, never on a transaction
+const ROOT_MEMBERS = new Set([
+    '$connect',
+    '$disconnect',
+    '$on',
+    '$extends'
+]);
+/**
+ * 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.
+ */
+class PrismaDatabase extends common_1.Database {
+    /** @internal */
+    _client;
+    /** @internal */
+    _proxy;
+    /**
+     * 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.
+     */
+    async onInit() {
+        try {
+            await this.connect();
+            await this.clientInstance().$queryRaw `SELECT 1`;
+        }
+        catch (error) {
+            const dbType = (0, common_1.resolveDatabaseType)(database_config_1.databaseConfig.TYPE, database_config_1.databaseConfig.URL);
+            const url = this.redactUrl(database_config_1.databaseConfig.URL);
+            common_1.logger.error(error, `Cannot connect to the ${dbType} database${url ? ` at ${url}` : ''}`);
+            // The next query creates a new client, which detects the capabilities of the database again
+            await this.disconnect().catch(() => undefined);
+            this._client = undefined;
+        }
+    }
+    async onDestroy() {
+        await this.disconnect();
+    }
+    async connect() {
+        if (this._client) {
+            return;
+        }
+        await this.clientInstance().$connect();
+    }
+    async disconnect() {
+        if (!this._client) {
+            return;
+        }
+        await this._client.$disconnect();
+        this._client = undefined;
+    }
+    /**
+     * Returns the Prisma client, which runs its queries in the transaction the
+     * current call runs in (see `runTransaction`), and on the connection otherwise.
+     */
+    client() {
+        this._proxy ??= this.transactionAwareClient();
+        return this._proxy;
+    }
+    async checkHealth() {
+        try {
+            await this.client().$queryRaw `SELECT 1`;
+            return { success: true };
+        }
+        catch (e) {
+            return { success: false, message: e.message };
+        }
+    }
+    /**
+     * 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.
+     */
+    async transaction(fn, options = {}) {
+        const isolationLevel = this.isolationLevel(options.isolationLevel);
+        const current = (0, internal_1.currentTransaction)();
+        if (current) {
+            if (options.isolationLevel && current.isolationLevel !== isolationLevel) {
+                throw new common_1.DatabaseError(common_1.ErrorCode.DatabaseInvalidTransaction, `Cannot run a ${isolationLevel} transaction inside a ` +
+                    `${current.isolationLevel ?? 'default'} isolation level transaction`);
+            }
+            return fn(current.tx);
+        }
+        for (let attempt = 0;; attempt++) {
+            const context = {
+                tx: undefined,
+                commitCallbacks: new Map(),
+                rollbackCallbacks: [],
+                isolationLevel
+            };
+            let result;
+            try {
+                result = await this.clientInstance().$transaction((tx) => {
+                    context.tx = tx;
+                    return (0, internal_1.runInTransaction)(context, () => fn(tx));
+                }, { isolationLevel, timeout: options.timeout, maxWait: options.maxWait });
+            }
+            catch (e) {
+                await (0, internal_1.settleTransaction)(context, false);
+                if (attempt < (options.retries ?? 0) && this.isWriteConflict(e)) {
+                    continue;
+                }
+                throw e;
+            }
+            await (0, internal_1.settleTransaction)(context, true);
+            return result;
+        }
+    }
+    /** @internal */
+    clientInstance() {
+        if (!this._client) {
+            this._client = (0, create_client_1.createClient)();
+        }
+        return this._client;
+    }
+    /** @internal */
+    isolationLevel(level) {
+        // SQLite runs every transaction serializable and rejects the other levels
+        const dbType = (0, common_1.resolveDatabaseType)(database_config_1.databaseConfig.TYPE, database_config_1.databaseConfig.URL);
+        if (dbType === common_1.DatabaseType.Sqlite) {
+            return common_1.IsolationLevel.Serializable;
+        }
+        return level;
+    }
+    /** @internal */
+    transactionAwareClient() {
+        return new Proxy({}, {
+            get: (_target, property) => {
+                const root = this.clientInstance();
+                const context = (0, internal_1.currentTransaction)();
+                if (property === '$transaction') {
+                    return (arg, options) => this.joinTransaction(root, context, arg, options);
+                }
+                const source = context && !ROOT_MEMBERS.has(property) ? context.tx : root;
+                const value = Reflect.get(source, property);
+                return typeof value === 'function' ? value.bind(source) : value;
+            }
+        });
+    }
+    /** @internal */
+    joinTransaction(root, context, arg, options) {
+        if (typeof arg === 'function') {
+            return this.transaction(arg, options);
+        }
+        // The batch form, whose queries were created on the current transaction
+        return context
+            ? Promise.all(arg)
+            : root.$transaction(arg, options);
+    }
+    /** @internal */
+    redactUrl(url) {
+        return url
+            .replace(/(\/\/[^:/@]*):[^@/]*@/, '$1:********@')
+            .replace(/((?:password|pwd)=)[^;&]*/gi, '$1********');
+    }
+    /** @internal */
+    isWriteConflict(error) {
+        // Followed through the errors wrapping it, i.e. a service's DatabaseError
+        for (let e = error; e; e = e.cause) {
+            if (e.code === 'P2034' || e.code === common_1.ErrorCode.DatabaseWriteConflict) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+exports.PrismaDatabase = PrismaDatabase;

package/database/run-transaction.d.ts

@@ -0,0 +1,21 @@
+import { IsolationLevel, TransactionOptions } from '@appweaver/common';
+type TransactionFn<T, Tx> = (tx: Tx) => Promise<T>;
+/**
+ * Runs the given function in a database transaction. Every service call and
+ * every query of the database client made while it runs is part of the
+ * transaction, which commits once the function resolves. An error thrown out of
+ * the function rolls the transaction back and is rethrown, while an error caught
+ * inside it does not.
+ *
+ * The resource events, the cache invalidation, and the removal of stored files
+ * wait for the commit, and are dropped on rollback. A call made inside another
+ * transaction joins it.
+ *
+ * @param {IsolationLevel | TransactionOptions} [options] - The isolation level or
+ * the transaction options, falling back to the database default and the config.
+ * @param {Function} fn - The function to run, receiving the transaction client.
+ * @return {Promise<Object>} The value returned by the function.
+ */
+export declare function runTransaction<T, Tx = any>(fn: TransactionFn<T, Tx>): Promise<T>;
+export declare function runTransaction<T, Tx = any>(options: IsolationLevel | `${IsolationLevel}` | TransactionOptions, fn: TransactionFn<T, Tx>): Promise<T>;
+export {};

package/database/run-transaction.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTransaction = runTransaction;
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+function runTransaction(optionsOrFn, fn) {
+    const db = (0, core_1.inject)(common_1.Database);
+    if (typeof optionsOrFn === 'function') {
+        return db.transaction(optionsOrFn);
+    }
+    const options = typeof optionsOrFn === 'string'
+        ? { isolationLevel: optionsOrFn }
+        : optionsOrFn;
+    return db.transaction(fn, options);
+}

package/export/export-config.d.ts

@@ -0,0 +1,7 @@
+export declare const exportConfig: Readonly<{
+    BATCH_SIZE: number;
+    CSV_DELIMITER: string;
+    CSV_JOIN_DELIMITER: string;
+    CSV_ADD_HEADERS: boolean;
+    CSV_ADD_SEP_ROW: boolean;
+}>;

package/export/export-config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportConfig = void 0;
+const typebox_1 = require("@sinclair/typebox");
+const common_1 = require("@appweaver/common");
+exports.exportConfig = (0, common_1.defineConfig)('export', {
+    /** Number of records per batch during export. Default: `1000`. */
+    BATCH_SIZE: typebox_1.Type.Integer({ default: 1000 }),
+    /** CSV field delimiter character. Default: `';'`. */
+    CSV_DELIMITER: typebox_1.Type.String({ default: ';' }),
+    /** Delimiter for joining array values in CSV cells. Default: `','`. */
+    CSV_JOIN_DELIMITER: typebox_1.Type.String({ default: ',' }),
+    /** Include a header row in CSV exports. Default: `true`. */
+    CSV_ADD_HEADERS: typebox_1.Type.Boolean({ default: true }),
+    /** Add a separator row (BOM) for Excel compatibility. Default: `false`. */
+    CSV_ADD_SEP_ROW: typebox_1.Type.Boolean({ default: false })
+});

package/export/export-service.d.ts

@@ -0,0 +1,22 @@
+import { Readable } from 'node:stream';
+import { QuerySort } from '@appweaver/common';
+export type ExportStream = {
+    stream: Readable;
+    fileName: string;
+    mimeType: string;
+};
+export declare class ExportService {
+    /**
+     * Exports data as a CSV stream based on the provided filter and sort parameters.
+     * The records are read batch by batch, each following the cursor of the
+     * previous one, so the export never counts the records up front.
+     *
+     * @param {string} modelName - The resource name for which to export data.
+     * @param {Object} [filter={}] - The filter conditions to apply when retrieving the data. Default is an empty object.
+     * @param {QuerySort} [sort='-createdAt'] - The sorting criteria for the data, given either as a comma-separated
+     * field list or as an object of field directions.
+     * @return {Promise<ExportStream>} A promise resolving to the export stream object, which includes the readable
+     * stream, MIME type, and file name for the CSV.
+     */
+    exportCsv(modelName: string, filter?: any, sort?: QuerySort): Promise<ExportStream>;
+}

package/export/export-service.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExportService = void 0;
+const node_stream_1 = require("node:stream");
+const common_1 = require("@appweaver/common");
+const export_config_1 = require("./export-config");
+const core_1 = require("@appweaver/core");
+const file_util_1 = require("../utils/file-util");
+const export_util_1 = require("../utils/export-util");
+class ExportService {
+    /**
+     * Exports data as a CSV stream based on the provided filter and sort parameters.
+     * The records are read batch by batch, each following the cursor of the
+     * previous one, so the export never counts the records up front.
+     *
+     * @param {string} modelName - The resource name for which to export data.
+     * @param {Object} [filter={}] - The filter conditions to apply when retrieving the data. Default is an empty object.
+     * @param {QuerySort} [sort='-createdAt'] - The sorting criteria for the data, given either as a comma-separated
+     * field list or as an object of field directions.
+     * @return {Promise<ExportStream>} A promise resolving to the export stream object, which includes the readable
+     * stream, MIME type, and file name for the CSV.
+     */
+    async exportCsv(modelName, filter = {}, sort = '-createdAt') {
+        const service = (0, core_1.injectService)(modelName);
+        let exportStream;
+        try {
+            const batchSize = export_config_1.exportConfig.BATCH_SIZE;
+            const mapValues = (items) => this.mapProperties(modelName, items);
+            const readBatch = (cursor) => service.query({
+                filter,
+                size: batchSize,
+                sort,
+                cursor,
+                totalCount: false
+            });
+            // Read before the stream is handed out, so a failing query becomes an
+            // error response instead of a truncated download
+            const firstBatch = await readBatch();
+            // A generator rather than a `read` callback, which the stream may re-enter
+            // while an awaited batch is pending and would then write it twice
+            async function* rows() {
+                if (export_config_1.exportConfig.CSV_ADD_SEP_ROW) {
+                    yield `SEP=${export_config_1.exportConfig.CSV_DELIMITER}\n`;
+                }
+                let batch = firstBatch;
+                let addHeaders = export_config_1.exportConfig.CSV_ADD_HEADERS;
+                while (batch) {
+                    let chunk;
+                    let next;
+                    try {
+                        if (batch.resultCount > 0) {
+                            chunk = (0, export_util_1.toCsv)(mapValues(batch.items), addHeaders);
+                            addHeaders = false;
+                        }
+                        // A next cursor is returned only while further records match
+                        next = batch.nextCursor
+                            ? await readBatch(batch.nextCursor)
+                            : undefined;
+                    }
+                    catch (e) {
+                        // End early rather than fail a download already in flight
+                        common_1.logger.error(e, `${modelName} export error`);
+                        next = undefined;
+                    }
+                    if (chunk !== undefined) {
+                        yield chunk;
+                    }
+                    batch = next;
+                }
+            }
+            exportStream = node_stream_1.Readable.from(rows(), { objectMode: false });
+        }
+        catch (e) {
+            throw new common_1.ExportError(common_1.ErrorCode.ExportFailed, `${modelName} export failed`, { model: modelName }, { cause: e });
+        }
+        const fileName = this.generateExportFileName(modelName, 'csv');
+        common_1.logger.debug({ modelName, filter, fileName }, 'CSV File export');
+        return { stream: exportStream, mimeType: 'text/csv', fileName };
+    }
+    /** @internal */
+    mapProperties(resourceName, items) {
+        const properties = [];
+        for (const item of items) {
+            const property = this.mapProperty(resourceName, item);
+            properties.push(property);
+        }
+        return properties;
+    }
+    /** @internal */
+    mapProperty(resourceName, item, resourceExportConfig, parentKey = '') {
+        const resourceModel = (0, core_1.injectModel)(resourceName);
+        const readModel = resourceModel.readModel;
+        const relationsModel = resourceModel.relationsModel;
+        const filesModel = resourceModel.filesModel;
+        const fieldsConfig = resourceExportConfig ?? resourceModel.config.export;
+        const property = {};
+        for (const key in item) {
+            let value = item[key];
+            const modelSchema = (0, common_1.extractSchemaProperties)(readModel, key);
+            const relationSchema = (0, common_1.extractSchemaProperties)(relationsModel, key);
+            const fileSchema = (0, common_1.extractSchemaProperties)(filesModel, key);
+            if (!modelSchema &&
+                !relationSchema &&
+                !fileSchema &&
+                !(0, common_1.isCountField)(key)) {
+                // Skip mapping for non-exposed fields.
+                continue;
+            }
+            // The records are read from the database rather than through a response
+            // schema, so the fields no response carries are dropped here instead.
+            if (modelSchema?.['hidden'] === true ||
+                resourceModel.config.virtual?.[key]?.output?.type === 'none') {
+                continue;
+            }
+            let header = parentKey ? `${parentKey}.${key}` : key;
+            const isArrayValue = (0, common_1.isArray)(value);
+            const exportField = fieldsConfig?.[key];
+            if (exportField) {
+                if (exportField.exclude === true) {
+                    // Skip mapping for excluded fields.
+                    continue;
+                }
+                if ((0, common_1.isString)(exportField.headerName)) {
+                    header = parentKey
+                        ? `${parentKey}.${exportField.headerName}`
+                        : exportField.headerName;
+                }
+                const mapValue = exportField.mapValue;
+                if (mapValue) {
+                    // A scalar value has no properties to read the configured field name
+                    // off, so it is resolved against the exported record itself.
+                    if ((0, common_1.isString)(mapValue) && !relationSchema && !fileSchema) {
+                        value = item?.[mapValue];
+                    }
+                    else {
+                        const mappedValues = [];
+                        // Transform value items using mapValue configuration.
+                        const subItems = isArrayValue ? value : [value];
+                        for (const subItem of subItems) {
+                            if ((0, common_1.isFunction)(mapValue)) {
+                                try {
+                                    mappedValues.push(mapValue(subItem));
+                                }
+                                catch (e) {
+                                    mappedValues.push('');
+                                    common_1.logger.error(e, 'Export value mapping error.');
+                                }
+                            }
+                            else if ((0, common_1.isString)(mapValue)) {
+                                mappedValues.push(subItem?.[mapValue]);
+                            }
+                        }
+                        value = mappedValues.join(',');
+                    }
+                }
+            }
+            // Recursively map relation and file fields if the value is an object.
+            // Arrays of plain values are written as a single column below.
+            if ((0, common_1.isPlainObject)(value) || (isArrayValue && (0, common_1.isPlainObject)(value[0]))) {
+                const relationName = (0, common_1.extractResourceName)(relationSchema ?? fileSchema);
+                if (!relationName) {
+                    continue;
+                }
+                const subItems = isArrayValue ? value : [value];
+                for (const subItem of subItems) {
+                    const mappedItem = this.mapProperty(relationName, subItem, exportField, header);
+                    for (const subKey in mappedItem) {
+                        if (subKey in property) {
+                            property[subKey] = [property[subKey], mappedItem[subKey]].join(export_config_1.exportConfig.CSV_JOIN_DELIMITER);
+                        }
+                        else {
+                            property[subKey] = mappedItem[subKey];
+                        }
+                    }
+                }
+            }
+            else {
+                property[header] = value;
+            }
+        }
+        return property;
+    }
+    /** @internal */
+    generateExportFileName(modelName, extension) {
+        return (0, file_util_1.generateFileName)(`${(0, common_1.plural)(modelName)}.${extension}`, '{name}_{year}{month}{day}_{hours}{minutes}{seconds}.{extension}');
+    }
+}
+exports.ExportService = ExportService;

package/export/index.d.ts

@@ -0,0 +1 @@
+export * from './export-service';

package/export/index.js

@@ -0,0 +1,17 @@
+"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("./export-service"), exports);

package/factory/create-model.d.ts

@@ -0,0 +1,11 @@
+import { ResourceModel, ResourceModelConfig } from '@appweaver/common';
+/**
+ * Creates a resource model from its configuration and defines it in the application context. The names of the
+ * declared fields are inferred from the configuration, so the `read`, `create`, and `update` options only accept
+ * existing fields.
+ *
+ * @param {ResourceModelConfig} config - The model configuration.
+ * @param {boolean} [override=false] - Whether to replace a model already defined under the same name.
+ * @return {ResourceModel} The created resource model.
+ */
+export declare function createModel<S extends string, R extends string, F extends string, V extends string>(modelConfig: ResourceModelConfig<S, R, F, V>, override?: boolean): ResourceModel;