@appweaver/data 0.0.0-stage → 2.0.1

package/seeder/create-seeder.d.ts

@@ -0,0 +1,29 @@
+import { Seeder } from './seeder';
+export type CreateSeederParams = {
+    /** A relative path where the application source code is located.
+     * This is usually the directory from which the createApp() function is called.
+     * (default: ./dist/src) */
+    scanPath?: string;
+    /** A relative path where the seeder functions are located.
+     * (default: ./dist/database/seeders) */
+    seedersPath?: string;
+    /** A flag indication if the seeder should continue execution even if an error occurs.
+     * (default: false) */
+    continueOnError?: boolean;
+    /** A boolean flag indicating whether the seeder should automatically
+     * start seeding after being created. (default: true) **/
+    autoSeed?: boolean;
+    /** A boolean flag indicating whether to automatically fix all warnings
+     * related to the seeders like wrong checksum or deleted seeder files.
+     * (default: false) **/
+    fixWarnings?: boolean;
+};
+/**
+ * Creates the database seeder, loading the providers of the project first, and runs the pending seeders unless
+ * `autoSeed` is disabled: the seeders of the modules declaring a `seeders` directory first, then the ones of the
+ * application.
+ *
+ * @param {CreateSeederParams} [params={}] - The seeder parameters.
+ * @return {Promise<Seeder>} The created seeder.
+ */
+export declare function createSeeder(params?: CreateSeederParams): Promise<Seeder>;

package/seeder/create-seeder.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSeeder = createSeeder;
+const common_1 = require("@appweaver/common");
+const database_config_1 = require("../database/database-config");
+const core_1 = require("@appweaver/core");
+const internal_1 = require("@appweaver/core/internal");
+const seeder_1 = require("./seeder");
+/**
+ * Creates the database seeder, loading the providers of the project first, and runs the pending seeders unless
+ * `autoSeed` is disabled: the seeders of the modules declaring a `seeders` directory first, then the ones of the
+ * application.
+ *
+ * @param {CreateSeederParams} [params={}] - The seeder parameters.
+ * @return {Promise<Seeder>} The created seeder.
+ */
+async function createSeeder(params = {}) {
+    const scanPath = (0, common_1.resolveSourcePath)(common_1.appConfig.BUILD_PATH, common_1.appConfig.SOURCE_PATH, params.scanPath, './dist/src');
+    const seedersPath = (0, common_1.resolveSourcePath)(common_1.appConfig.BUILD_PATH, database_config_1.databaseConfig.SEEDERS_DIR_PATH, params.seedersPath, './dist/database/seeders');
+    // Define the providers and the services of the modules
+    const modules = await (0, core_1.discoverModules)({ scanPath });
+    await (0, internal_1.loadProviders)(modules, scanPath);
+    const seeder = new seeder_1.Seeder(seedersPath, params.continueOnError, params.fixWarnings, modules.flatMap(({ module }) => module.seeders ? [{ name: module.name, path: module.seeders }] : []));
+    if (params.autoSeed !== false) {
+        await seeder.seed();
+    }
+    return seeder;
+}

package/seeder/index.d.ts

@@ -0,0 +1,2 @@
+export * from './create-seeder';
+export * from './seeder';

package/seeder/index.js

@@ -0,0 +1,18 @@
+"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("./create-seeder"), exports);
+__exportStar(require("./seeder"), exports);

package/seeder/resources/seeder/model.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@appweaver/common").ResourceModel;
+export default _default;

package/seeder/resources/seeder/model.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const create_model_1 = require("../../../factory/create-model");
+exports.default = (0, create_model_1.createModel)({
+    name: 'Seeder',
+    tableName: '_seeders',
+    generateTypes: false,
+    id: {
+        type: 'string',
+        generator: 'uuid()'
+    },
+    audit: {
+        updatedAt: false,
+        createdAt: false,
+        createdById: false
+    },
+    scalars: {
+        checksum: {
+            type: 'string',
+            maxLength: 255
+        },
+        seederName: {
+            type: 'string',
+            unique: true,
+            maxLength: 511
+        },
+        startedAt: {
+            type: 'dateTime'
+        },
+        finishedAt: {
+            type: 'dateTime'
+        },
+        logs: {
+            type: 'string',
+            required: false
+        }
+    }
+});

package/seeder/seeder.d.ts

@@ -0,0 +1,29 @@
+import { LifecycleManager } from '@appweaver/core/internal';
+/** The seeders directory of a module, whose seeders run before the ones of the application. */
+export type ModuleSeeders = {
+    /** The name of the module, prefixing the names of its seeders, i.e. `billing/1-plans`. */
+    name: string;
+    /** The absolute path of the seeders directory. */
+    path: string;
+};
+/**
+ * Represents a seeder class that manages the application seeders processes.
+ */
+export declare class Seeder extends LifecycleManager {
+    private readonly _dirPath;
+    private readonly _continueOnError;
+    private readonly _fixWarnings;
+    private readonly _moduleSeeders;
+    constructor(_dirPath: string, _continueOnError?: boolean, _fixWarnings?: boolean, _moduleSeeders?: ModuleSeeders[]);
+    /**
+     * Executes the seeders by discovering, validating, and running seeder files.
+     * Logs the seeding process, including warnings for checksum mismatches
+     * and files that do not exist but are present in the database table.
+     *
+     * @return Resolves when all seeders have been processed. Logs relevant
+     * information during execution.
+     */
+    seed(): Promise<void>;
+    /** Destroys the services the seeder started, i.e. the database connection. */
+    close(): Promise<void>;
+}

package/seeder/seeder.js

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Seeder = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const common_1 = require("@appweaver/common");
+const internal_1 = require("@appweaver/core/internal");
+const core_1 = require("@appweaver/core");
+/**
+ * Represents a seeder class that manages the application seeders processes.
+ */
+class Seeder extends internal_1.LifecycleManager {
+    _dirPath;
+    _continueOnError;
+    _fixWarnings;
+    _moduleSeeders;
+    /** @internal */
+    _db = (0, core_1.inject)(common_1.Database);
+    constructor(_dirPath, _continueOnError = false, _fixWarnings = false, _moduleSeeders = []) {
+        super();
+        this._dirPath = _dirPath;
+        this._continueOnError = _continueOnError;
+        this._fixWarnings = _fixWarnings;
+        this._moduleSeeders = _moduleSeeders;
+    }
+    /**
+     * Executes the seeders by discovering, validating, and running seeder files.
+     * Logs the seeding process, including warnings for checksum mismatches
+     * and files that do not exist but are present in the database table.
+     *
+     * @return Resolves when all seeders have been processed. Logs relevant
+     * information during execution.
+     */
+    async seed() {
+        await this.init();
+        // The seeders of the modules run first, in their load order
+        const directories = [
+            ...this._moduleSeeders,
+            { name: '', path: this._dirPath }
+        ];
+        const seederFiles = [];
+        const missing = [];
+        for (const { name, path: dirPath } of directories) {
+            try {
+                seederFiles.push(...(await this.loadSeederFiles(dirPath, name)));
+            }
+            catch {
+                console.warn(`Seeders directory ${dirPath} is not accessible`);
+                missing.push(name);
+            }
+        }
+        if (missing.length === directories.length) {
+            console.error('No seeders directory is accessible');
+            return;
+        }
+        let calledSeedersCount = 0;
+        const relativePath = this._dirPath
+            .replace(process.cwd(), '.')
+            .replace(/\\/g, '/');
+        const modulesCount = this._moduleSeeders.length;
+        console.log(`${seederFiles.length} seeder${seederFiles.length === 1 ? '' : 's'} found in ${relativePath}${modulesCount > 0
+            ? ` and ${modulesCount} module${modulesCount === 1 ? '' : 's'}`
+            : ''}`);
+        console.log('');
+        // For each seeder file, skip if it has already been seeded, otherwise
+        // execute all of it's exported functions and write results to a database
+        for (const seederFile of seederFiles) {
+            const seederName = seederFile.name;
+            const seeder = await this.getSeeder(seederName);
+            if (seeder) {
+                const checksum = await this.seederHash(seederFile.path);
+                if (checksum !== seeder.checksum) {
+                    console.warn(`Warning: seeder ${seederName} has different checksum: ${checksum}, expected checksum: ${seeder.checksum}`);
+                    if (this._fixWarnings) {
+                        await this._db.client().seeder.update({
+                            where: { id: seeder.id },
+                            data: { checksum }
+                        });
+                        console.log('Fix: seeder checksum updated');
+                    }
+                    console.log('');
+                }
+                continue;
+            }
+            console.log(`Seeding ${seederName}...`);
+            await this.executeSeeder(seederFile);
+            console.log(`${seederName} seeded`);
+            console.log('');
+            calledSeedersCount++;
+        }
+        // The seeders of a missing directory are not reported as deleted
+        const seedersWithoutFiles = (await this.findSeedersWithoutFiles(seederFiles)).filter((seeder) => !missing.includes(this.seederOwner(seeder.seederName)));
+        for (const seeder of seedersWithoutFiles) {
+            console.warn(`Warning: seeder ${seeder.seederName} does not exist but is present in database table`);
+            if (this._fixWarnings) {
+                await this._db.client().seeder.delete({ where: { id: seeder.id } });
+                console.log('Fix: removed seeder from database');
+            }
+            console.log('');
+        }
+        if (calledSeedersCount === 0) {
+            console.log(`No pending seeders to execute`);
+        }
+        else {
+            console.log(`Executed ${calledSeedersCount} seeder${calledSeedersCount === 1 ? '' : 's'}`);
+        }
+    }
+    /** Destroys the services the seeder started, i.e. the database connection. */
+    async close() {
+        await this.destroy();
+    }
+    /** @internal */
+    async loadSeederFiles(dirPath, moduleName) {
+        const entries = await promises_1.default.readdir(dirPath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && /\.(js|ts)$/.test(e.name) && !e.name.endsWith('.d.ts'))
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' }))
+            .map((fileName) => {
+            const name = fileName.replace(/\.(js|ts)$/, '');
+            return {
+                path: node_path_1.default.join(dirPath, fileName),
+                name: moduleName ? `${moduleName}/${name}` : name
+            };
+        });
+    }
+    /** @internal */
+    async executeSeeder(seederFile) {
+        const start = new Date();
+        const { value, error } = await (0, common_1.importModule)(seederFile.path);
+        if (error) {
+            if (this._continueOnError) {
+                console.error(error);
+                return;
+            }
+            throw error;
+        }
+        const logs = [];
+        // Execute all exported functions from a seeder file and log errors or
+        // function responses
+        for (const seederFn of Object.values(value)) {
+            if ((0, common_1.isFunction)(seederFn)) {
+                try {
+                    const result = await seederFn();
+                    if (result) {
+                        logs.push(JSON.stringify(result));
+                    }
+                }
+                catch (e) {
+                    if (!this._continueOnError) {
+                        throw e;
+                    }
+                    console.error(e);
+                    logs.push(`Error: ${e.message}`);
+                }
+            }
+        }
+        const checksum = await this.seederHash(seederFile.path);
+        // Insert seeder result into the database
+        await this._db.client().seeder.create({
+            data: {
+                checksum,
+                seederName: seederFile.name,
+                startedAt: start,
+                finishedAt: new Date(),
+                logs: logs.length > 0 ? logs.join('\n') : null
+            }
+        });
+    }
+    /** @internal */
+    async findSeedersWithoutFiles(seederFiles) {
+        const seederNames = seederFiles.map((file) => file.name);
+        return this._db.client().seeder.findMany({
+            where: {
+                seederName: { notIn: seederNames }
+            }
+        });
+    }
+    /** @internal */
+    seederOwner(seederName) {
+        const owner = this._moduleSeeders.find(({ name }) => seederName.startsWith(`${name}/`));
+        return owner?.name ?? '';
+    }
+    /** @internal */
+    async getSeeder(seederName) {
+        return this._db.client().seeder.findFirst({ where: { seederName } });
+    }
+    /** @internal */
+    async seederHash(seederFile) {
+        return (0, common_1.makeHash)(node_fs_1.default.createReadStream(seederFile, 'utf8'));
+    }
+}
+exports.Seeder = Seeder;

package/storage/file-service.d.ts

@@ -0,0 +1,133 @@
+import { ContentStream, Resource, ResourceClient, ResourceId } from '@appweaver/common';
+import { File } from '../types/generated';
+import { FileBuffer, UploadedFile, UploadPart } from '../types/storage';
+export type FileStream = {
+    content: ContentStream;
+    fileName: string;
+    mimeType: string;
+    start: number;
+    end: number;
+};
+/** A file the clients download from the URL of its storage, i.e. a signed URL of a cloud storage. */
+export type FileRedirect = {
+    url: string;
+    fileName: string;
+    mimeType: string;
+};
+export declare class FileService {
+    /**
+     * Searches for a file by its name from a database.
+     *
+     * @param {string} fileName - The name of the file to search for.
+     * @return {Promise<File>} A promise that resolves to the file object if found.
+     * @throws {FileError} Throws an error if the file name is placed under a reserved storage path, if a database error
+     * occurs, or if the file is not found.
+     */
+    findByName(fileName: string): Promise<File>;
+    /**
+     * Streams a file from storage, handling authorization and range-based requests.
+     *
+     * @param {string} fileName - The name of the file to stream.
+     * @param {string} [range] - An optional range header specifying the byte range to stream.
+     * @return {Promise<FileStream>} A promise that resolves to a file stream object containing the content, metadata, and
+     * range details.
+     * @throws {FileError} `FILE_NOT_FOUND` if the file does not exist.
+     * @throws {FileError} `FILE_FORBIDDEN` if user access to the file is forbidden.
+     * @throws {FileError} `FILE_STORAGE_ERROR` if an error occurs while reading the file from storage.
+     */
+    stream(fileName: string, range?: string): Promise<FileStream>;
+    /**
+     * Opens a file for a download, handling authorization like {@link stream}: the URL of its storage when the storage
+     * serves its files directly, otherwise the stream of the file.
+     *
+     * @param {string} fileName - The name of the file to download.
+     * @param {string} [range] - An optional range header specifying the byte range to stream.
+     * @return {Promise<FileStream | FileRedirect>} The URL of the file, or its stream.
+     * @throws {FileError} The errors of {@link stream}.
+     */
+    download(fileName: string, range?: string): Promise<FileStream | FileRedirect>;
+    /**
+     * Saves a file to storage, validates its properties, and associates it with a specific resource and client.
+     *
+     * @param {UploadedFile} data The multipart file object containing the file data, field name, filename, and metadata.
+     * @param {Resource} resource The resource object with which the file is being associated.
+     * @param {ResourceClient} client The database client responsible for handling the resource.
+     * @return {Promise<File>} A promise that resolves to the saved file object or rejects with an error if the operation
+     * fails.
+     * @throws {FileError} Throws an error if file validation, storage, or resource association fails.
+     */
+    saveFile(data: UploadedFile, resource: Resource, client: ResourceClient): Promise<File>;
+    /**
+     * Saves an in-memory file to storage and associates it with a file field of a specific resource. Behaves exactly like
+     * {@link saveFile}, except the content is taken from a buffer instead of a multipart upload, which makes it usable
+     * outside a file upload request, for an avatar downloaded from an OAuth2 provider or an image the application
+     * generates itself.
+     *
+     * @param {string} fieldName The file field of the resource the file is saved to.
+     * @param {FileBuffer} file The file content, along with its original name and media type.
+     * @param {Resource} resource The resource object with which the file is being associated.
+     * @param {ResourceClient} client The database client responsible for handling the resource.
+     * @return {Promise<File>} A promise that resolves to the saved file object or rejects with an error if the operation
+     * fails.
+     * @throws {FileError} Throws an error if file validation, storage, or resource association fails.
+     */
+    saveBuffer(fieldName: string, file: FileBuffer, resource: Resource, client: ResourceClient): Promise<File>;
+    /**
+     * Saves files received as an asynchronous iterable of multipart data.
+     *
+     * @param {AsyncIterableIterator<UploadPart>} parts - The asynchronous iterable providing multipart data where each
+     * part is expected to represent a file or other data.
+     * @param {Resource} resource - The resource associated with the files being saved, providing additional contextual
+     * information.
+     * @param {ResourceClient} client - The database client responsible for handling resource-related operations, such as
+     * database interaction.
+     * @return {Promise<File[]>} A promise that resolves to an array of successfully saved files. Rejects with an error
+     * if one or more files fail to save.
+     */
+    saveFiles(parts: AsyncIterableIterator<UploadPart>, resource: Resource, client: ResourceClient): Promise<File[]>;
+    /**
+     * Deletes a file from the storage and database if it meets the specified conditions.
+     *
+     * @param {string} fileName - The name of the file to be deleted.
+     * @param {string} fieldName - The field associated with the resource to which the file belongs.
+     * @param {Resource} resource - The resource that the file is associated with.
+     * @param {ResourceClient} client - The client instance representing the resource's type.
+     * @return {Promise<File>} A promise that resolves with the deleted file information upon successful deletion.
+     * @throws {FileError} If the file is not associated with the provided resource or client,
+     *                     if the current user does not have permission to delete the file,
+     *                     if there is an error removing the file from storage,
+     *                     or if there is an error deleting the file from the database.
+     */
+    deleteFile(fileName: string, fieldName: string, resource: Resource, client: ResourceClient): Promise<File>;
+    /**
+     * Deletes a list of files associated with a given resource using the provided resource client.
+     *
+     * @param {Record<string, string | string[]>} fileNames - An object where the keys correspond to file fields and the
+     * values are either a string (single file name) or an array of file names to be deleted.
+     * @param {Resource} resource - The resource instance associated with the files to be deleted.
+     * @param {ResourceClient} client - The resource a client used to handle deletion operations.
+     * @return {Promise<File[]>} A promise that resolves to an array of files that were successfully deleted. Rejects with
+     * an error if no files could be deleted.
+     */
+    deleteFiles(fileNames: Record<string, string | string[]>, resource: Resource, client: ResourceClient): Promise<File[]>;
+    /**
+     * Deletes all files associated with a resource removed from the database,
+     * for the file fields not set to `onResourceDeleted: 'keep'`.
+     *
+     * @param {string} resourceName - The resource model name.
+     * @param {ResourceId} id - The ID of the deleted resource.
+     * @return {Promise<File[]>} A promise that resolves to the list of successfully deleted files.
+     */
+    deleteResourceFiles(resourceName: string, id: ResourceId): Promise<File[]>;
+    /**
+     * Deletes all files associated with the given deleted resources of one model from the storage and the database. A
+     * resource removed from the database loses the files of every field not set to `onResourceDeleted: 'keep'`, while a
+     * soft deleted resource only loses the files of the fields set to `onResourceSoftDeleted: 'delete'`.
+     *
+     * @param {string} resourceName - The resource model name.
+     * @param {ResourceId[]} ids - The IDs of the deleted resources.
+     * @param {boolean} [softDeleted=false] - Whether the resources were soft deleted.
+     * @return {Promise<File[]>} A promise that resolves to the list of successfully deleted files.
+     */
+    deleteResourcesFiles(resourceName: string, ids: ResourceId[], softDeleted?: boolean): Promise<File[]>;
+}