@appweaver/core 1.0.0

package/LICENSE

@@ -0,0 +1 @@
+UNLICENSED

package/README.md

@@ -0,0 +1,7 @@
+# Appweaver - Core
+
+> Simple, fast, and reliable web application builder tool.
+
+## License
+
+UNLICENSED

package/app/application.d.ts

@@ -0,0 +1,43 @@
+import { Server } from '../types';
+import { LifecycleManager } from './lifecycle-manager';
+/**
+ * Represents an application that manages the lifecycle of a server and all
+ * defined services.
+ */
+export declare class Application extends LifecycleManager {
+    private readonly _server;
+    private _started;
+    constructor(_server: Server);
+    /**
+     * Retrieves the Fastify instance.
+     *
+     * @return {Server} The underlying Fastify server instance.
+     */
+    get server(): Server;
+    /**
+     * Starts the application by initializing the server and calls onInit lifecycle methods for
+     * services that implement the `OnInit` interface. This process also includes logging the environment
+     * in which the application is running, freezing the application context to prevent further changes,
+     * and starting a server to listen for incoming requests.
+     *
+     * @return {Promise<string>} A promise that resolves to a string denoting the server URL on a successful start or
+     * empty string if server was not started.
+     */
+    start(startServer?: boolean): Promise<string>;
+    /**
+     * Stops the server by closing all active connections and releasing resources by calling onDestroy lifecycle
+     * methods for services that implement the `OnDestroy` interface.
+     * This method should be called to gracefully shut down the server.
+     *
+     * @return {Promise<void>} A promise that resolves when the server has been successfully stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Generates and returns the OpenAPI specification in JSON or YAML format.
+     *
+     * @param {'json' | 'yaml'} [format='json'] - The format in which to generate specification.
+     * @return {Promise<string>} A promise that resolves to a JSON or YAML formatted string containing the OpenAPI
+     * specification.
+     */
+    spec(format?: 'json' | 'yaml'): Promise<string>;
+}

package/app/application.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Application = void 0;
+const common_1 = require("@appweaver/common");
+const context_1 = require("../context");
+const lifecycle_manager_1 = require("./lifecycle-manager");
+/**
+ * Represents an application that manages the lifecycle of a server and all
+ * defined services.
+ */
+class Application extends lifecycle_manager_1.LifecycleManager {
+    _server;
+    _started = false;
+    constructor(_server) {
+        super();
+        this._server = _server;
+    }
+    /**
+     * Retrieves the Fastify instance.
+     *
+     * @return {Server} The underlying Fastify server instance.
+     */
+    get server() {
+        return this._server;
+    }
+    /**
+     * Starts the application by initializing the server and calls onInit lifecycle methods for
+     * services that implement the `OnInit` interface. This process also includes logging the environment
+     * in which the application is running, freezing the application context to prevent further changes,
+     * and starting a server to listen for incoming requests.
+     *
+     * @return {Promise<string>} A promise that resolves to a string denoting the server URL on a successful start or
+     * empty string if server was not started.
+     */
+    async start(startServer = true) {
+        if (this._started) {
+            common_1.logger.warn('Trying to start already started application.');
+            return this._server.addresses()[0]?.address ?? '';
+        }
+        this._started = true;
+        common_1.logger.info(`Application started in "${common_1.config.APP_ENV}" environment`);
+        await this.init();
+        Object.freeze(context_1.context);
+        // Add a termination handler for gracefully stopping the application
+        process.on('SIGINT', async () => {
+            await this.stop();
+            process.exit(0);
+        });
+        // Add unhandled rejection handler
+        process.on('unhandledRejection', async (err) => {
+            common_1.logger.fatal(err, 'Unhandled rejection');
+            try {
+                await this.stop();
+            }
+            catch (e) {
+                common_1.logger.error(e, `Error while trying to stop application`);
+            }
+            process.exit(1);
+        });
+        // Add uncaught exception handler
+        process.on('uncaughtException', async (err) => {
+            common_1.logger.fatal(err, 'Uncaught exception');
+            try {
+                await this.stop();
+            }
+            catch (e) {
+                common_1.logger.error(e, `Error while trying to stop application`);
+            }
+            process.exit(2);
+        });
+        if (startServer) {
+            return this._server.listen({
+                port: common_1.config.SERVER_PORT,
+                host: common_1.config.SERVER_HOST
+            });
+        }
+        return '';
+    }
+    /**
+     * Stops the server by closing all active connections and releasing resources by calling onDestroy lifecycle
+     * methods for services that implement the `OnDestroy` interface.
+     * This method should be called to gracefully shut down the server.
+     *
+     * @return {Promise<void>} A promise that resolves when the server has been successfully stopped.
+     */
+    async stop() {
+        if (!this._started) {
+            common_1.logger.warn('Trying to stop already stopped or not started application.');
+            return;
+        }
+        common_1.logger.info('Application stopped');
+        this._started = false;
+        await this.destroy();
+        await this._server.close();
+    }
+    /**
+     * Generates and returns the OpenAPI specification in JSON or YAML format.
+     *
+     * @param {'json' | 'yaml'} [format='json'] - The format in which to generate specification.
+     * @return {Promise<string>} A promise that resolves to a JSON or YAML formatted string containing the OpenAPI
+     * specification.
+     */
+    async spec(format = 'json') {
+        await this._server.ready();
+        const document = this._server.swagger({ yaml: format === 'yaml' });
+        if (typeof document === 'string') {
+            return document;
+        }
+        return JSON.stringify(document, null, 4);
+    }
+}
+exports.Application = Application;

package/app/create-app.d.ts

@@ -0,0 +1,32 @@
+import { LoadResourcePaths } from '../resource';
+import { Application } from './application';
+export type CreateAppParams = {
+    /** A relative path where the application will load resources and other features.
+     * This is usually the directory from which the createApp() function is called.
+     * (default: ./dist/src) */
+    scanPath?: string;
+    /** A boolean flag indicating whether the application should automatically
+     * start after being created. (default: true) **/
+    autoStart?: boolean;
+    /** A boolean flag indicating whether the web server should automatically
+     * start after being created. (default: true) **/
+    autoStartServer?: boolean;
+    /** An object containing the path patterns for loading resources from. */
+    resourcePaths?: LoadResourcePaths;
+    /** Path pattern used for finding modules that export application logic
+     * (default: `./src/"*"/index.ts`) */
+    modulePaths?: string;
+    /** A boolean flag indicating whether the application should automatically load
+     * resources configured and exported using factory functions. (default: true) */
+    autoLoadResources?: boolean;
+    /** A boolean flag indicating whether the application should automatically load
+     * export modules from the project source directory. (default: true) */
+    autoLoadModules?: boolean;
+};
+/**
+ * Creates and initializes an application instance with the provided parameters.
+ *
+ * @param {CreateAppParams} [params={}] Configuration parameters for creating the application.
+ * @return {Promise<Application>} A promise that resolves to the initialized application instance.
+ */
+export declare function createApp(params?: CreateAppParams): Promise<Application>;

package/app/create-app.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = createApp;
+const common_1 = require("@appweaver/common");
+const context_1 = require("../context");
+const server_1 = require("../server");
+const resource_1 = require("../resource");
+const load_providers_1 = require("./load-providers");
+const load_modules_1 = require("./load-modules");
+const application_1 = require("./application");
+/**
+ * Creates and initializes an application instance with the provided parameters.
+ *
+ * @param {CreateAppParams} [params={}] Configuration parameters for creating the application.
+ * @return {Promise<Application>} A promise that resolves to the initialized application instance.
+ */
+async function createApp(params = {}) {
+    common_1.logger.debug({ configFiles: common_1.configFiles }, 'Configuration loaded');
+    const scanPath = (0, common_1.resolveSourcePath)(common_1.config.APP_BUILD_PATH, common_1.config.APP_SOURCE_PATH, params.scanPath, './dist/src');
+    // Load all defined providers from this project
+    (0, load_providers_1.loadProviders)(scanPath);
+    // Load resource models, routes, policies and services
+    if (params.autoLoadResources !== false) {
+        await (0, resource_1.loadResources)(scanPath, params.resourcePaths);
+    }
+    // Load exported application files
+    if (params.autoLoadModules !== false) {
+        await (0, load_modules_1.loadModules)(scanPath, params.modulePaths);
+    }
+    // Create a Fastify server instance
+    const server = (0, server_1.createServer)();
+    context_1.context.server = server;
+    const app = new application_1.Application(server);
+    if (params.autoStart !== false) {
+        await app.start(params.autoStartServer);
+    }
+    return app;
+}

package/app/index.d.ts

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

package/app/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("./application"), exports);
+__exportStar(require("./create-app"), exports);

package/app/lifecycle-manager.d.ts

@@ -0,0 +1,20 @@
+export declare abstract class LifecycleManager {
+    private _initialized;
+    private readonly _initServices;
+    private readonly _destroyServices;
+    /**
+     * Initializes the services and sets the initialized state.
+     * This method ensures that the initialization logic is executed only once.
+     *
+     * @return A promise that resolves when all services have completed their initialization.
+     */
+    init(): Promise<void>;
+    /**
+     * Releases resources and cleans up any initialized services.
+     * This method ensures that all registered services perform their individual cleanup operations.
+     * It also sets the initialized state to false.
+     *
+     * @return A promise that resolves when all cleanup operations are completed.
+     */
+    destroy(): Promise<void>;
+}

package/app/lifecycle-manager.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleManager = void 0;
+const common_1 = require("@appweaver/common");
+const context_1 = require("../context");
+class LifecycleManager {
+    _initialized = false;
+    _initServices = (0, context_1.injectAllWhere)((def) => (0, common_1.isLifecycleInit)(def.value));
+    _destroyServices = (0, context_1.injectAllWhere)((def) => (0, common_1.isLifecycleDestroy)(def.value));
+    /**
+     * Initializes the services and sets the initialized state.
+     * This method ensures that the initialization logic is executed only once.
+     *
+     * @return A promise that resolves when all services have completed their initialization.
+     */
+    async init() {
+        if (this._initialized) {
+            return;
+        }
+        await Promise.all([
+            ...this._initServices.map((service) => service.onInit())
+        ]);
+        this._initialized = true;
+    }
+    /**
+     * Releases resources and cleans up any initialized services.
+     * This method ensures that all registered services perform their individual cleanup operations.
+     * It also sets the initialized state to false.
+     *
+     * @return A promise that resolves when all cleanup operations are completed.
+     */
+    async destroy() {
+        if (!this._initialized) {
+            return;
+        }
+        await Promise.all([
+            ...this._destroyServices.map((service) => service.onDestroy())
+        ]);
+        this._initialized = false;
+    }
+}
+exports.LifecycleManager = LifecycleManager;

package/app/load-modules.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Loads and initializes modules exported from the application using the provided base directory and file pattern.
+ *
+ * @param {string} [baseDir] - The base directory containing the module files to load.
+ * @param {string} [moduleFilesPattern] - Path patterns for loading files that export application logic like:
+ * models, routes, plugins, scheduled jobs, queue workers, etc.
+ * @return {Promise<void>} A promise that resolves when the modules are successfully loaded,
+ * or rejects if an error occurs during the process.
+ */
+export declare function loadModules(baseDir?: string, moduleFilesPattern?: string): Promise<void>;

package/app/load-modules.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadModules = loadModules;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const common_1 = require("@appweaver/common");
+/**
+ * Loads and initializes modules exported from the application using the provided base directory and file pattern.
+ *
+ * @param {string} [baseDir] - The base directory containing the module files to load.
+ * @param {string} [moduleFilesPattern] - Path patterns for loading files that export application logic like:
+ * models, routes, plugins, scheduled jobs, queue workers, etc.
+ * @return {Promise<void>} A promise that resolves when the modules are successfully loaded,
+ * or rejects if an error occurs during the process.
+ */
+async function loadModules(baseDir, moduleFilesPattern) {
+    const cwd = baseDir ?? process.cwd();
+    const pathPattern = moduleFilesPattern || common_1.config.APP_SCAN_FILES_PATTERN;
+    // Find all project files matching provided glob pattern
+    const modulePaths = await (0, common_1.findFilesByPattern)(pathPattern, cwd);
+    for (const path of modulePaths) {
+        await loadModule(path);
+    }
+}
+/**
+ * Loads a module from the specified file path. Reads the file content and
+ * ensures it meets the criteria before attempting to dynamically import the module.
+ * Logs an error if module loading fails.
+ *
+ * @param {string} modulePath - The file path of the module to be loaded.
+ * @return {Promise<void>} A promise that resolves when the module is successfully loaded or rejects if an error occurs.
+ */
+async function loadModule(modulePath) {
+    try {
+        const fileContent = await promises_1.default.readFile(modulePath, 'utf8');
+        if (fileContent.split('\n').length < 3) {
+            return;
+        }
+    }
+    catch (error) {
+        common_1.logger.error(error, `Error while loading module`);
+        return;
+    }
+    const { error } = await (0, common_1.importModule)(modulePath);
+    if (error) {
+        throw error;
+    }
+}

package/app/load-providers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Loads and registers the core and infrastructure service definitions.
+ * This method initializes and sets up various service components, such as the
+ * database, cache, queue system, mailer, storage, and authentication services, among others.
+ *
+ * @param {string} baseDir - The base directory containing the module files.
+ */
+export declare function loadProviders(baseDir: string): void;

package/app/load-providers.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadProviders = loadProviders;
+const common_1 = require("@appweaver/common");
+const context_1 = require("../context");
+/**
+ * Loads and registers the core and infrastructure service definitions.
+ * This method initializes and sets up various service components, such as the
+ * database, cache, queue system, mailer, storage, and authentication services, among others.
+ *
+ * @param {string} baseDir - The base directory containing the module files.
+ */
+function loadProviders(baseDir) {
+    // Common infrastructure services
+    (0, context_1.loadProvider)(baseDir, common_1.config.DATABASE_PROVIDER, common_1.Database);
+    (0, context_1.loadProvider)(baseDir, common_1.config.STORAGE_PROVIDER, common_1.Storage);
+    (0, context_1.loadProvider)(baseDir, common_1.config.MEMORY_PROVIDER, common_1.Memory);
+    (0, context_1.loadProvider)(baseDir, common_1.config.CACHE_PROVIDER, common_1.Cache);
+    (0, context_1.loadProvider)(baseDir, common_1.config.EVENTS_PROVIDER, common_1.Events);
+    (0, context_1.loadProvider)(baseDir, common_1.config.SECURITY_STORE_PROVIDER, common_1.SecurityStore);
+    (0, context_1.loadProvider)(baseDir, common_1.config.REDIS_PROVIDER, common_1.Redis, false);
+    (0, context_1.loadProvider)(baseDir, common_1.config.QUEUE_PROVIDER, common_1.Queue, false);
+    (0, context_1.loadProvider)(baseDir, common_1.config.MAILER_PROVIDER, common_1.Mailer, false);
+    (0, context_1.loadProvider)(baseDir, common_1.config.SCHEDULER_PROVIDER, common_1.Scheduler, false);
+    // Core feature services
+    (0, context_1.loadProvider)(__dirname, '../mailer/email-service', undefined, false);
+    (0, context_1.loadProvider)(__dirname, '../cache/cache-service');
+    (0, context_1.loadProvider)(__dirname, '../storage/file-service');
+    (0, context_1.loadProvider)(__dirname, '../security/auth-service');
+    (0, context_1.loadProvider)(__dirname, '../security/account/account-service');
+    (0, context_1.loadProvider)(__dirname, '../export/export-service');
+    (0, context_1.loadProvider)(__dirname, '../health/health-service');
+}

package/cache/cache-service.d.ts

@@ -0,0 +1,72 @@
+import { AuthUser, Cache } from '@appweaver/common';
+export declare class CacheService {
+    /**
+     * Retrieves the cache instance associated with this service.
+     *
+     * @return {Cache} The current cache instance.
+     */
+    get cache(): Cache;
+    /**
+     * Retrieves a cached value associated with the specified key.
+     *
+     * @param {string} key - The key used to look up the cached value.
+     * @return A promise that resolves to the cached value if the key exists, or null if the key is not found.
+     */
+    getCachedValue<T>(key: string): Promise<T | null>;
+    /**
+     * Adds a key-value pair to the cache if the key does not already exist.
+     * Optionally allows specifying a time-to-live (TTL) for the cached item.
+     *
+     * @param {string} key - The unique key to identify the value in the cache.
+     * @param {Object} value - The value to store in the cache.
+     * @param {number} [ttl] - Optional time-to-live for the cache entry in seconds.
+     * @param {boolean} [replace=false] - Optional flag that indicates if the existing cache entry should be replaced
+     * with the new value and ttl.
+     * @return {Promise<boolean>} A promise that resolves to true if the key-value pair was added, or false if the key
+     * already exists.
+     */
+    addToCache(key: string, value: any, ttl?: number, replace?: boolean): Promise<boolean>;
+    /**
+     * Removes a cached value associated with the specified key from the cache store.
+     *
+     * @param {string} key - The key associated with the cached value to be removed.
+     * @return {Promise<boolean>} A promise that resolves to `true` if the value was successfully removed, or
+     * `false` otherwise.
+     */
+    removeCachedValue(key: string): Promise<boolean>;
+    /**
+     * Invalidates the cache for the specified model and action type based on the configured cache invalidation strategy.
+     *
+     * @param {string} modelName - The name of the model whose cache needs to be invalidated.
+     * @param {Extract<ActionType, 'create' | 'update' | 'delete' | 'uploadFiles' | 'deleteFiles'>} action - The action type
+     * that triggered the cache invalidation (e.g., 'create', 'update', 'delete', 'uploadFiles', or 'fileDelete').
+     * @return {Promise<void>} Resolves when the cache invalidation process is completed.
+     */
+    invalidateCache(modelName: string, action: 'create' | 'update' | 'delete' | 'uploadFiles' | 'deleteFiles'): Promise<void>;
+    /**
+     * Builds a unique cache key based on the provided input parameters. The key is constructed
+     * using properties such as the base key, HTTP method, URL, request body, model name, and any
+     * associated relations. It also includes optional user-specific data and cache invalidation settings.
+     *
+     * @param {Object} data Input data for constructing the cache key.
+     * @param {string} data.baseKey The base key that serves as the starting point of the cache key.
+     * @param {string} [data.method] The HTTP method (e.g., GET, POST) associated with the key.
+     * @param {string} [data.url] The URL associated with the request.
+     * @param {string} [data.body] The stringified request body, which will be hashed if present.
+     * @param {string} [data.modelName] The name of the model to associate with the cache key.
+     * @param {string[]} [data.relations] A list of related model names to associate with the cache key.
+     * @param {boolean} [data.skipInvalidation] Whether to skip invalidation logic for this cache key.
+     * @param {AuthUser} [data.authUser] The authenticated user information, if applicable, to create user-specific keys.
+     * @return {string} The generated cache key string.
+     */
+    buildCacheKey(data: {
+        baseKey: string;
+        method?: string;
+        url?: string;
+        body?: string;
+        modelName?: string;
+        relations?: string[];
+        skipInvalidation?: boolean;
+        authUser?: AuthUser;
+    }): string;
+}