@cyberismo/data-handler 0.0.14 → 0.0.15

package/dist/containers/project.js

@@ -12,18 +12,18 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 // node
-import { dirname, join, resolve, sep } from 'node:path';
-import { readdir } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { constants as fsConstants, copyFile, mkdir, readdir, unlink, writeFile, } from 'node:fs/promises';
 import { CardContainer } from './card-container.js'; // base class
 import { CalculationEngine } from './project/calculation-engine.js';
 import { CardLocation, } from '../interfaces/project-interfaces.js';
-import { getFilesSync, pathExists } from '../utils/file-utils.js';
+import { pathExists } from '../utils/file-utils.js';
 import { generateRandomString } from '../utils/random.js';
-import { isTemplateCard } from '../utils/card-utils.js';
+import { cardPathParts, isModulePath, isTemplateCard, } from '../utils/card-utils.js';
 import { ProjectConfiguration } from '../project-settings.js';
 import { ProjectPaths } from './project/project-paths.js';
 import { readJsonFile } from '../utils/json.js';
-import { resourceName, resourceNameToString, } from '../utils/resource-utils.js';
+import { pathToResourceName, resourceName, resourceNameToString, } from '../utils/resource-utils.js';
 import { ResourcesFrom, ResourceCollector, } from './project/resource-collector.js';
 import { Validate } from '../commands/validate.js';
 import { CalculationResource } from '../resources/calculation-resource.js';
@@ -36,7 +36,8 @@ import { ReportResource } from '../resources/report-resource.js';
 import { TemplateResource } from '../resources/template-resource.js';
 import { WorkflowResource } from '../resources/workflow-resource.js';
 import { ContentWatcher } from './project/project-content-watcher.js';
-import { pathToResourceName } from '../utils/resource-utils.js';
+import { getChildLogger } from '../utils/log-utils.js';
+import { ROOT } from '../utils/constants.js';
 // Re-export this, so that classes that use Project do not need to have separate import.
 export { ResourcesFrom };
 /**
@@ -45,25 +46,30 @@ export { ResourcesFrom };
 export class Project extends CardContainer {
     watchResourceChanges;
     calculationEngine;
-    resources;
-    projectPaths;
-    settings;
-    validator;
-    resourceWatcher;
     // Created resources are held in a cache.
     // In the cache, key is resource name, and data is resource metadata (as JSON).
     createdResources = new Map();
+    logger = getChildLogger({ module: 'Project' });
+    projectPaths;
+    resources;
+    resourceWatcher;
+    settings;
+    validator;
     constructor(path, watchResourceChanges) {
-        super(path, '');
+        const settings = new ProjectConfiguration(join(path, '.cards', 'local', Project.projectConfigFileName));
+        super(path, settings.cardKeyPrefix, '');
         this.watchResourceChanges = watchResourceChanges;
+        this.settings = settings;
+        this.logger.info({ path }, 'Initializing project');
         this.calculationEngine = new CalculationEngine(this);
-        this.settings = new ProjectConfiguration(join(path, '.cards', 'local', Project.projectConfigFileName));
         this.projectPaths = new ProjectPaths(path);
         this.resources = new ResourceCollector(this);
         this.containerName = this.settings.name;
         // todo: implement project validation
         this.validator = Validate.getInstance();
+        this.logger.info({ resourcesFolder: this.paths.resourcesFolder }, 'Collecting local resources');
         this.resources.collectLocalResources();
+        this.logger.info({ name: this.containerName }, 'Project initialization complete');
         const ignoreRenameFileChanges = true;
         // Watch changes in .cards if there are multiple instances of Project being
         // run concurrently.
@@ -88,7 +94,48 @@ export class Project extends CardContainer {
             });
         }
     }
-    // Removes current version of resource from cache.
+    // Changes a card's parent in the cache and updates all relationships.
+    changeParent(updatedCard, previousParent) {
+        if (previousParent && previousParent !== ROOT) {
+            this.removeCachedChildren(previousParent, updatedCard.key);
+        }
+        if (updatedCard.parent && updatedCard.parent !== ROOT) {
+            this.updateCachedChildren(updatedCard.parent, updatedCard);
+        }
+        this.cardCache.updateCard(updatedCard.key, updatedCard);
+    }
+    // Finds specific module.
+    async findModule(moduleName) {
+        return (await this.resources.resources('modules')).find((item) => item.name === moduleName && item.path);
+    }
+    // Handles attachment changes after filesystem operations.
+    async handleAttachmentChange(cardKey, operation, fileName) {
+        if (operation === 'added') {
+            this.cardCache.addAttachment(cardKey, fileName);
+        }
+        else if (operation === 'removed') {
+            this.cardCache.deleteAttachment(cardKey, fileName);
+        }
+        else if (operation === 'refresh') {
+            const newAttachments = this.cardCache.getCardAttachments(cardKey);
+            if (newAttachments) {
+                this.cardCache.updateCardAttachments(cardKey, newAttachments);
+            }
+        }
+    }
+    // Determines the parent card key from a card's filesystem path.
+    parentFromPath(cardPath) {
+        return cardPathParts(this.projectPrefix, cardPath).parents.at(-1) || 'root';
+    }
+    // Remove children from a card in the card cache
+    removeCachedChildren(parentKey, childKey) {
+        const parentCard = this.cardCache.getCard(parentKey);
+        if (parentCard && parentCard.children) {
+            parentCard.children = parentCard.children.filter((child) => child !== childKey);
+            this.cardCache.updateCard(parentCard.key, parentCard);
+        }
+    }
+    // Removes current version of a resource from the resource cache.
     // Then re-creates the resource with current data and caches the value again.
     // If the value wasn't in the cache before, it will be added.
     async replaceCacheValue(resourceName) {
@@ -97,19 +144,65 @@ export class Project extends CardContainer {
             this.createdResources.delete(resourceName);
         }
         const resourceData = await this.resource(resourceName);
-        if (!resourceData)
-            return;
-        this.createdResources.set(resourceName, resourceData);
-    }
-    // Finds specific module.
-    async findModule(moduleName) {
-        return (await this.resources.resources('modules')).find((item) => item.name === moduleName && item.path);
+        if (resourceData) {
+            this.createdResources.set(resourceName, resourceData);
+        }
     }
     // Returns (local or all) resources of a given type.
-    // @todo: if this would be public, we could remove cardTypes(), fieldTypes(), ... and similar APIs
     async resourcesOfType(type, from = ResourcesFrom.localOnly) {
         return this.resources.resources(type, from);
     }
+    // Updates children in the card cache
+    updateCachedChildren(parentKey, newChild) {
+        const parentCard = this.cardCache.getCard(parentKey);
+        if (parentCard) {
+            // Add or update the child in the parent's children array
+            const existingChildIndex = parentCard.children?.findIndex((child) => child === newChild.key);
+            if (existingChildIndex === -1) {
+                parentCard.children.push(newChild.key);
+            }
+            this.cardCache.updateCard(parentCard.key, parentCard);
+        }
+    }
+    /**
+     * Populate template cards into the card cache.
+     */
+    async populateTemplateCards() {
+        try {
+            // Gets local & module templates
+            const templateResources = await this.templates();
+            const prefixes = await this.projectPrefixes();
+            const loadPromises = templateResources.map(async (template) => {
+                try {
+                    this.validator.validResourceName('templates', template.name, prefixes);
+                }
+                catch (error) {
+                    this.logger.warn({ templateName: template.name, error }, `Template name '${template.name}' does not follow required format, skipping`);
+                    return;
+                }
+                const templateResource = new TemplateResource(this, resourceName(template.name));
+                const templateObject = templateResource.templateObject();
+                const isCreated = templateObject && templateObject.isCreated();
+                if (!templateObject || !isCreated) {
+                    return;
+                }
+                await this.cardCache.populateFromPath(templateObject.templateCardsFolder(), false);
+            });
+            await Promise.all(loadPromises);
+            // Once all templates have been fetched, build child-parent relationships.
+            this.cardCache.populateChildrenRelationships();
+        }
+        catch (error) {
+            this.logger.error({ error }, 'Failed to populate template cards into the card cache');
+        }
+    }
+    /**
+     * Populate both the project cards, and all template cards into card cache.
+     */
+    async populateCardsCache() {
+        await this.cardCache.populateFromPath(this.paths.cardRootFolder);
+        await this.populateTemplateCards();
+    }
     /**
      * Add a given 'resource' to the local resource arrays.
      * @param resource Resource to add.
@@ -119,13 +212,45 @@ export class Project extends CardContainer {
         this.resources.add(resource);
         this.createdResources.set(resource.name, data);
     }
+    /**
+     * Returns all template cards from the project. This includes all module templates' cards.
+     * @returns all the template cards from the project
+     */
+    allTemplateCards() {
+        return this.cardCache.getAllTemplateCards();
+    }
     /**
      * Returns an array of all the attachments in the project card's (excluding ones in templates).
      * @returns all attachments in the project.
      */
-    async attachments() {
+    attachments() {
         return super.attachments(this.paths.cardRootFolder);
     }
+    /**
+     * Returns attachments from cards at a specific path using the card cache.
+     * This method allows templates to access attachments from the shared cache.
+     * @param path The path to get attachments from
+     * @returns Array of attachments from cards at the specified path
+     */
+    attachmentsByPath(path) {
+        return super.attachments(path);
+    }
+    /**
+     * Returns all the attachments in the template cards.
+     * @returns all the attachments in the template cards.
+     */
+    async attachmentsFromTemplates() {
+        const templateAttachments = [];
+        const templates = await this.templates();
+        for (const template of templates) {
+            const templateResource = new TemplateResource(this, resourceName(template.name));
+            const templateObject = templateResource.templateObject();
+            if (templateObject) {
+                templateAttachments.push(...templateObject.attachments());
+            }
+        }
+        return templateAttachments;
+    }
     /**
      * Returns an array of all the calculation files (*.lp) in the project.
      * @param from Defines where resources are collected from.
@@ -135,117 +260,119 @@ export class Project extends CardContainer {
         return this.resources.resources('calculations', from);
     }
     /**
-     * Returns path to card's attachment folder.
+     * Returns path to a card's attachment folder.
      * @param cardKey card key
-     * @returns path to card's attachment folder.
-     * @throws if card path cannot be found
+     * @returns path to a card's attachment folder.
      */
-    async cardAttachmentFolder(cardKey) {
-        // Check if it is a template card.
-        if (await this.isTemplateCard(cardKey)) {
-            const cardPath = await this.cardFolder(cardKey);
-            return join(cardPath, 'a');
+    cardAttachmentFolder(cardKey) {
+        const pathToCard = this.findCard(cardKey).path;
+        return join(pathToCard, 'a');
+    }
+    /**
+     * Creates an attachment for a card.
+     * @param cardKey The card to add attachment to
+     * @param attachmentName The name for the attachment file
+     * @param attachmentData The attachment data (file path or buffer)
+     * @throws If trying to add attachment to module card, or if attachment is not found
+     */
+    async createCardAttachment(cardKey, attachmentName, attachmentData) {
+        const attachmentFolder = this.cardAttachmentFolder(cardKey);
+        // Check if this is a module template
+        if (isModulePath(attachmentFolder)) {
+            throw new Error(`Cannot modify imported module`);
         }
-        const pathToProjectCard = this.pathToCard(cardKey);
-        if (!pathToProjectCard) {
-            throw new Error(`Card '${cardKey}' not found`);
+        // Create the attachment folder if it doesn't exist
+        await mkdir(attachmentFolder, { recursive: true });
+        const attachmentPath = join(attachmentFolder, basename(attachmentName));
+        if (Buffer.isBuffer(attachmentData)) {
+            await writeFile(attachmentPath, attachmentData, { flag: 'wx' });
         }
-        return join(this.paths.cardRootFolder, pathToProjectCard, 'a');
+        else {
+            try {
+                await copyFile(attachmentData, attachmentPath, fsConstants.COPYFILE_EXCL);
+            }
+            catch {
+                throw new Error(`Attachment file not found: ${attachmentData}`);
+            }
+        }
+        // Update cache
+        await this.handleAttachmentChange(cardKey, 'added', basename(attachmentName));
     }
     /**
-     * Returns details (as defined by cardDetails) of a card.
-     * @param cardKey card key (project prefix and a number, e.g. test_1)
-     * @param cardDetails which card details are returned.
-     * @returns Card details, or undefined if the card cannot be found.
+     * Removes an attachment from a card.
+     * @param cardKey The card to remove attachment from
+     * @param fileName The name of the attachment file to remove
+     * @throws if trying to remove module card attachment, or the attachment was not found.
      */
-    async cardDetailsById(cardKey, cardDetails) {
-        return this.findSpecificCard(cardKey, cardDetails);
+    async removeCardAttachment(cardKey, fileName) {
+        const attachmentFolder = this.cardAttachmentFolder(cardKey);
+        // Modules cannot be modified.
+        if (isModulePath(attachmentFolder)) {
+            throw new Error(`Cannot modify imported module`);
+        }
+        const attachmentPath = join(attachmentFolder, fileName);
+        try {
+            await unlink(attachmentPath);
+        }
+        catch (error) {
+            this.logger.error({ error }, 'Removing card attachment');
+            throw new Error(`Attachment not found: ${fileName}`);
+        }
+        await this.handleAttachmentChange(cardKey, 'removed', fileName);
     }
     /**
-     * Returns path to card's folder.
+     * Returns path to a card's folder.
      * @param cardKey card key
-     * @returns path to card's folder.
+     * @returns path to a card's folder.
      */
     async cardFolder(cardKey) {
-        const found = await super.findCard(this.paths.cardRootFolder, cardKey);
+        const found = super.findCard(cardKey);
         if (found) {
             return found.path;
         }
         const templates = await this.templates();
-        const templatePromises = templates.map(async (template) => {
+        const templatePromises = templates.map((template) => {
             const templateObject = new TemplateResource(this, resourceName(template.name)).templateObject();
             const templateCard = templateObject
-                ? await templateObject.findSpecificCard(cardKey)
+                ? templateObject.findCard(cardKey)
                 : undefined;
-            return templateCard ? templateCard.path : '';
+            const path = templateCard ? templateCard.path : '';
+            return path;
         });
         const templatePaths = await Promise.all(templatePromises);
         return templatePaths.find((path) => path !== '') || '';
     }
     /**
-     * Splits card path to parts. Returns the parts.
-     * Returned parts are: prefix, card key, array of parents and template name. Template name is returned only for template cards.
-     * @param cardPath path to a card
-     * @returns card path logical parts
-     * @throws when called with wrong path, or wrong card owner
-     * todo: if prefix would be parameter; this could be static, or util method
-     */
-    cardPathParts(cardPath) {
-        const pathParts = cardPath.split(sep);
-        const cardKey = pathParts.at(pathParts.length - 1);
-        const parents = [];
-        let prefix = this.projectPrefix;
-        let template = '';
-        let startIndex = -1;
-        let templatesNameIndex = -1;
-        const cardRootIndex = pathParts.indexOf('cardRoot');
-        const projectInternalsIndex = pathParts.indexOf('.cards');
-        if (projectInternalsIndex === -1 && cardRootIndex >= 0) {
-            startIndex = projectInternalsIndex;
-        }
-        else if (projectInternalsIndex >= 0 && cardRootIndex === -1) {
-            const templatesIndex = pathParts.indexOf('templates');
-            startIndex = templatesIndex;
-            if (templatesIndex === -1) {
-                throw new Error(`Invalid card path. Template card must have 'templates' in path`);
-            }
-            const modulesIndex = pathParts.indexOf('modules');
-            if (modulesIndex !== -1) {
-                prefix = pathParts.at(modulesIndex + 1) || '';
-            }
-            templatesNameIndex = templatesIndex + 1;
-            template = `${prefix}/templates/${pathParts.at(templatesNameIndex)}`;
-        }
-        else {
-            throw new Error(`Card must be either project card, or template card`);
-        }
-        // Look for parents in the path.
-        let previousWasParent = false;
-        for (let index = startIndex; index <= pathParts.length; index++) {
-            if (previousWasParent) {
-                previousWasParent = false;
-                parents.push(pathParts.at(index - 2));
-            }
-            const cardsSubFolder = pathParts.at(index) === 'c';
-            const ignoreOrNotTemplatesParent = index - 1 !== templatesNameIndex || templatesNameIndex === -1;
-            if (cardsSubFolder && ignoreOrNotTemplatesParent) {
-                previousWasParent = true;
+     * Fetches full Card data for given card keys
+     * @param cardIds array of card keys to fetch
+     * @returns Card data to the given card keys
+     */
+    cardKeysToCards(cardIds) {
+        const cards = [];
+        for (const cardId of cardIds) {
+            const card = this.cardCache.getCard(cardId);
+            if (card) {
+                cards.push(card);
             }
         }
-        return {
-            cardKey: cardKey,
-            parents: parents,
-            prefix: prefix,
-            template: template,
-        };
+        return cards;
     }
     /**
-     * Returns an array of all the cards in the project. Cards have content and metadata
-     * @param path Optional path from which to fetch the cards. Generally it is best to fetch from Project root, e.g. Project.cardRootFolder
-     * @param details Which details to include in the cards; by default only "content" and "metadata" are included.
+     * Accessor for cards cache.
+     * Used by template container (it needs to access project's cache, not their own instance).
+     * @note Should not be used directly (other than Template).
+     */
+    get cardsCache() {
+        return this.cardCache;
+    }
+    /**
+     * Returns an array of all the cards in the project.
+     * @note These are project cards only, by default (unless path dictates otherwise).
+     * @param path Path from which to fetch the cards. Generally it is best to fetch from Project root, e.g. Project.cardRootFolder
+     * @param details Which details to include in the cards; by default all details are included.
      * @returns all cards from the given path in the project.
      */
-    async cards(path = this.paths.cardRootFolder, details = { content: true, metadata: true }) {
+    cards(path = this.paths.cardRootFolder, details) {
         return super.cards(path, details);
     }
     /**
@@ -256,6 +383,21 @@ export class Project extends CardContainer {
     async cardTypes(from = ResourcesFrom.all) {
         return this.resources.resources('cardTypes', from);
     }
+    /**
+     * Returns children of a given card; as Card array
+     * @param card Parent card to fetch children from
+     * @returns children of a given card; as Card array
+     */
+    childrenCards(card) {
+        const cards = [];
+        for (const child of card.children) {
+            const card = this.cardCache.getCard(child);
+            if (card) {
+                cards.push(card);
+            }
+        }
+        return cards;
+    }
     /**
      * Updates all local resources.
      */
@@ -265,8 +407,8 @@ export class Project extends CardContainer {
     /**
      * Updates all imported module resources.
      */
-    async collectModuleResources() {
-        await this.resources.moduleImported();
+    collectModuleResources() {
+        this.resources.moduleImported();
     }
     /**
      * Returns project configuration.
@@ -284,7 +426,7 @@ export class Project extends CardContainer {
         if (!card || !card.path || !isTemplateCard(card)) {
             return undefined;
         }
-        const { template } = this.cardPathParts(card.path);
+        const { template } = cardPathParts(this.projectPrefix, card.path);
         return new TemplateResource(this, resourceName(template)).templateObject();
     }
     /**
@@ -326,30 +468,8 @@ export class Project extends CardContainer {
      * @param details Defines which card details are included in the return values.
      * @returns specific card details, or undefined if card is not part of the project.
      */
-    async findSpecificCard(cardToFind, details = {}) {
-        let card;
-        if (details.location === CardLocation.projectOnly ||
-            details.location === CardLocation.all ||
-            !details.location) {
-            card = await super.findCard(this.paths.cardRootFolder, cardToFind, details);
-        }
-        if (!card &&
-            (details.location === CardLocation.templatesOnly ||
-                details.location === CardLocation.all ||
-                !details.location)) {
-            const templates = await this.templates();
-            for (const template of templates) {
-                const templateObject = new TemplateResource(this, resourceName(template.name)).templateObject();
-                if (!templateObject)
-                    continue;
-                // optimize: execute each find in template parallel
-                card = await templateObject.findSpecificCard(cardToFind, details);
-                if (card) {
-                    break;
-                }
-            }
-        }
-        return card;
+    findCard(cardToFind, details) {
+        return super.findCard(cardToFind, details);
     }
     /**
      * Returns an array of all the graph models in the project.
@@ -372,57 +492,87 @@ export class Project extends CardContainer {
      * @param changedCard Card that was changed.
      */
     async handleCardChanged(changedCard) {
+        // Notify the calculation engine about the change
         return this.calculationEngine.handleCardChanged(changedCard);
     }
     /**
      * When cards are removed.
      * @param deletedCard Card that is to be removed.
      */
-    async handleDeleteCard(deletedCard) {
+    async handleCardDeleted(deletedCard) {
+        // Delete children from the cache first
+        if (deletedCard.children && deletedCard.children.length > 0) {
+            for (const child of deletedCard.children) {
+                try {
+                    const childCard = this.findCard(child);
+                    await this.handleCardDeleted(childCard);
+                }
+                catch {
+                    this.logger.warn(`Accessing child '${child}' of '${deletedCard.key}' when deleting cards caused an exception`);
+                    continue;
+                }
+            }
+        }
+        await super.removeCard(deletedCard.key);
         return this.calculationEngine.handleDeleteCard(deletedCard);
     }
+    /**
+     * When card is moved.
+     * @param movedCard Card that moved
+     * @param newParentCard New parent for the 'movedCard'
+     * @param oldParentCard Previous parent of the 'movedCard'
+     */
+    async handleCardMoved(movedCard, newParentCard, oldParentCard) {
+        if (newParentCard) {
+            this.cardCache.updateCard(newParentCard.key, newParentCard);
+        }
+        if (oldParentCard) {
+            this.cardCache.updateCard(oldParentCard.key, oldParentCard);
+        }
+        this.cardCache.updateCard(movedCard.key, movedCard);
+        // todo: it would be enough to just update parent, previous parent and changed card
+        this.cardCache.populateChildrenRelationships();
+        await this.handleCardChanged(movedCard);
+        await this.calculationEngine.handleCardMoved();
+    }
     /**
      * When new cards are added.
      * @param cards Added cards.
      */
     async handleNewCards(cards) {
+        // Add new cards to the card cache
+        cards.forEach((card) => {
+            const cardWithParent = {
+                ...card,
+                parent: card.parent || this.parentFromPath(card.path),
+            };
+            this.cardCache.updateCard(cardWithParent.key, cardWithParent);
+            // Update the parent's children list in the cache
+            if (cardWithParent.parent && cardWithParent.parent !== ROOT) {
+                this.updateCachedChildren(cardWithParent.parent, cardWithParent);
+            }
+        });
         return this.calculationEngine.handleNewCards(cards);
     }
-    /**
-     * Checks if a given card is part of this project.
-     * @param cardKey card to check.
-     * @returns true if a given card is found from project, false otherwise.
-     */
-    hasCard(cardKey) {
-        return super.hasCard(cardKey, this.paths.cardRootFolder);
-    }
     /**
      * Adds a module from project.
-     * @param module Name of the module
+     * @param module Module to add
      */
     async importModule(module) {
         // Add module as a dependency.
         await this.configuration.addModule(module);
-        await this.collectModuleResources();
+        this.collectModuleResources();
+        await this.populateTemplateCards();
+        this.logger.info(`Imported module '${module.name}'`);
     }
     /**
-     * Checks if given path is a project.
+     * Checks if a given path is a project.
      * @param path Path to a project
      * @returns true, if in the given path there is a project; false otherwise
      */
     static isCreated(path) {
         return pathExists(join(path, 'cardRoot'));
     }
-    /**
-     * Returns whether card is a template card or not
-     * @param cardKey card to check.
-     * @todo: This is only used from 'remove'. Could it use the static checker?
-     * @returns true, if card is template card; false otherwise
-     */
-    async isTemplateCard(cardKey) {
-        const templateCards = await this.allTemplateCards();
-        return templateCards.find((card) => card.key === cardKey) != null;
-    }
     /**
      * Returns an array of all the link types in the project.
      * @param from Defines where resources are collected from.
@@ -435,13 +585,15 @@ export class Project extends CardContainer {
      * Returns an array of cards in the project, in the templates or both.
      * Cards don't have content and nor metadata.
      * @param cardsFrom Where to return cards from (project, templates, or both)
-     * @returns all cards in the project.
+     * @returns all cards in the project per container.
      */
     async listCards(cardsFrom = CardLocation.all) {
         const cardListContainer = [];
         if (cardsFrom === CardLocation.all ||
             cardsFrom === CardLocation.projectOnly) {
-            const projectCards = (await super.cards(this.paths.cardRootFolder)).map((item) => item.key);
+            const projectCards = super
+                .cards(this.paths.cardRootFolder)
+                .map((item) => item.key);
             cardListContainer.push({
                 name: this.projectName,
                 type: 'project',
@@ -455,8 +607,8 @@ export class Project extends CardContainer {
                 const templateObject = new TemplateResource(this, resourceName(template.name)).templateObject();
                 if (templateObject) {
                     // todo: optimization - do all this in parallel
-                    const templateCards = await templateObject.listCards();
-                    if (templateCards) {
+                    const templateCards = templateObject.listCards();
+                    if (templateCards.length) {
                         cardListContainer.push({
                             name: template.name,
                             type: 'template',
@@ -475,45 +627,24 @@ export class Project extends CardContainer {
      * @note that cardIDs are not sorted.
      */
     async listCardIds(cardsFrom = CardLocation.all) {
-        const promises = [];
-        if (cardsFrom === CardLocation.all ||
-            cardsFrom === CardLocation.projectOnly) {
-            promises.push(super
-                .cards(this.paths.cardRootFolder)
-                .then((cards) => new Set(cards.map((card) => card.key))));
+        const cardContainers = await this.listCards(cardsFrom);
+        const allCardIDs = new Set();
+        for (const container of cardContainers) {
+            const cards = container.cards;
+            cards.forEach((card) => allCardIDs.add(card));
         }
-        if (cardsFrom === CardLocation.all ||
-            cardsFrom === CardLocation.templatesOnly) {
-            promises.push((async () => {
-                const templates = await this.templates();
-                const templateResources = templates.map((template) => new TemplateResource(this, resourceName(template.name)));
-                const templateObjectsResults = await Promise.allSettled(templateResources);
-                const templateObjects = templateObjectsResults
-                    .filter((result) => result.status === 'fulfilled' && result.value !== null)
-                    .map((result) => result.value);
-                const listCardsResults = await Promise.allSettled(templateObjects.map((obj) => obj.templateObject().listCards()));
-                const templateCardIds = new Set();
-                listCardsResults
-                    .filter((result) => result.status === 'fulfilled')
-                    .forEach((result) => {
-                    result.value.forEach((card) => templateCardIds.add(card.key));
-                });
-                return templateCardIds;
-            })());
-        }
-        const allCardIdSets = await Promise.all(promises);
-        return new Set(allCardIdSets.flatMap((set) => [...set]));
+        return allCardIDs;
     }
     /**
      * Returns details of a certain module.
      * @param moduleName Name of the module.
-     * @returns module details, or undefined if workflow cannot be found.
+     * @returns module details, or undefined if module cannot be found.
      */
     async module(moduleName) {
         const module = await this.findModule(moduleName);
         if (module && module.path) {
             const modulePath = join(module.path, module.name);
-            const moduleConfig = (await readJsonFile(join(modulePath, Project.projectConfigFileName)));
+            const moduleConfig = await readJsonFile(join(modulePath, Project.projectConfigFileName));
             return {
                 name: moduleConfig.name,
                 modules: moduleConfig.modules,
@@ -624,15 +755,12 @@ export class Project extends CardContainer {
         return this.projectPaths;
     }
     /**
-     * Returns full path to a given card.
-     * @param cardKey card to check path for.
-     * @returns path to a given card.
+     * Populates the card cache, if it has not been populated.
      */
-    pathToCard(cardKey) {
-        const allFiles = getFilesSync(this.paths.cardRootFolder);
-        const cardIndexJsonFile = join(cardKey, Project.cardMetadataFile);
-        const foundFile = allFiles.find((file) => file.includes(cardIndexJsonFile));
-        return foundFile ? dirname(foundFile) : '';
+    async populateCaches() {
+        if (!this.cardCache.isPopulated) {
+            await this.populateCardsCache();
+        }
     }
     /**
      * Returns project name.
@@ -656,6 +784,7 @@ export class Project extends CardContainer {
         const prefixes = [this.projectPrefix];
         let files;
         try {
+            // TODO: Could be optimized so that prefixes are stored once fetched.
             files = await readdir(this.paths.modulesFolder, {
                 withFileTypes: true,
                 recursive: true,
@@ -670,11 +799,39 @@ export class Project extends CardContainer {
             const configurationPrefixes = await Promise.all(configurationPromises);
             prefixes.push(...configurationPrefixes);
         }
-        catch {
-            // do nothing if readdir throws // TODO: Log it
+        catch (error) {
+            this.logger.error({ error }, 'Failed to collect prefixes in use');
         }
         return prefixes;
     }
+    /**
+     * Removes a module from the project
+     * @param module Module (name) to remove.
+     */
+    async removeModule(moduleName) {
+        const toBeRemovedTemplates = this.resources.moduleResources.resourceArray('templates', moduleName);
+        // First, remove cards from the cache
+        for (const template of toBeRemovedTemplates) {
+            this.cardCache.deleteCardsFromTemplate(template.name);
+        }
+        // Then, remove module from project configuration
+        await this.configuration.removeModule(moduleName);
+        this.collectModuleResources();
+        this.logger.info(`Removed module '${moduleName}'`);
+    }
+    /**
+     * Removes a resource from Project.
+     * @param resource Resource to remove.
+     */
+    removeResource(resource) {
+        // Template cards must be removed from the cache when resource is removed.
+        if (resource.path.includes('templates')) {
+            const templateName = resourceNameToString(resourceName(resource.name));
+            this.cardCache.deleteCardsFromTemplate(templateName);
+        }
+        this.resources.remove(resource);
+        this.createdResources.delete(resource.name);
+    }
     /**
      * Array of reports in the project.
      * @param from Defines where resources are collected from.
@@ -698,20 +855,12 @@ export class Project extends CardContainer {
         }
         return handleBarFiles;
     }
-    /**
-     * Removes a resource from Project.
-     * @param resource Resource to remove.
-     */
-    removeResource(resource) {
-        this.resources.remove(resource);
-        this.createdResources.delete(resource.name);
-    }
     /**
      * Returns metadata from a given resource
      * @param name Name of a resource
      * @returns Metadata from the resource.
      */
-    async resource(name) {
+    resource(name) {
         const resName = resourceName(name);
         if (this.createdResources.has(resourceNameToString(resName))) {
             const value = this.createdResources.get(resourceNameToString(resName));
@@ -805,33 +954,22 @@ export class Project extends CardContainer {
      * Show cards of a project.
      * @returns an array of all project cards in the project.
      */
-    async showProjectCards() {
+    showProjectCards() {
         return this.showCards(this.paths.cardRootFolder);
     }
-    /**
-     * Returns all template cards from the project. This includes all module templates' cards.
-     * @param cardDetails which details to fetch. Optional.
-     * @returns all the template cards from the project
-     */
-    async allTemplateCards(cardDetails) {
-        const templates = await this.templates();
-        const cards = [];
-        for (const template of templates) {
-            const templateCards = await this.templateCards(template.name, cardDetails);
-            if (templateCards)
-                cards.push(...templateCards);
-        }
-        return cards;
-    }
     /**
      * Returns cards from single template.
-     * @param templateName Name of the template
-     * @param cardDetails Card information
+     * @param templateName Name of the template (supports both full names like 'decision/templates/decision' and short names like 'decision')
      * @returns List of cards from template.
      */
-    async templateCards(templateName, cardDetails) {
-        const templateObject = new TemplateResource(this, resourceName(templateName)).templateObject();
-        return await templateObject?.cards('', cardDetails);
+    templateCards(templateName) {
+        const templateCards = this.cardCache.getAllTemplateCards();
+        return templateCards.filter((cachedCard) => {
+            if (cachedCard.location === 'project') {
+                return false;
+            }
+            return cachedCard.location === templateName;
+        });
     }
     /**
      * Array of templates in the project.
@@ -842,20 +980,19 @@ export class Project extends CardContainer {
         return this.resources.resources('templates', from);
     }
     /**
-     * Update card content.
-     * @param cardKey card's ID that is updated.
+     * Update a card's content.
+     * @param cardKey card key to update.
      * @param content changed content
      */
     async updateCardContent(cardKey, content) {
-        const card = await this.findCard(this.basePath, cardKey, {
-            metadata: true,
-            content: true,
-        });
-        if (!card) {
-            throw new Error(`Card '${cardKey}' does not exist in the project`);
-        }
+        const card = this.findCard(cardKey);
         card.content = content;
+        // Update lastUpdated timestamp in metadata
+        if (card.metadata) {
+            card.metadata.lastUpdated = new Date().toISOString();
+        }
         await this.saveCard(card);
+        await this.handleCardChanged(card);
     }
     /**
      * Updates card metadata's single key.
@@ -864,16 +1001,13 @@ export class Project extends CardContainer {
      * @param newValue changed value for the key
      */
     async updateCardMetadataKey(cardKey, changedKey, newValue) {
-        const templateCard = await this.isTemplateCard(cardKey);
-        const card = await this.findCard(templateCard ? this.paths.templatesFolder : this.paths.cardRootFolder, cardKey, {
-            metadata: true,
-        });
-        if (!card) {
-            throw new Error(`Card '${cardKey}' does not exist in the project`);
-        }
+        const card = this.findCard(cardKey);
         if (!card.metadata || card.metadata[changedKey] === newValue) {
             return;
         }
+        const isRankChange = changedKey === 'rank';
+        const previousPath = isRankChange ? card.path : undefined;
+        const previousParent = isRankChange ? card.parent : undefined;
         const cardAsRecord = card.metadata;
         cardAsRecord[changedKey] = newValue;
         const invalidCard = isTemplateCard(card)
@@ -882,26 +1016,58 @@ export class Project extends CardContainer {
         if (invalidCard.length !== 0) {
             throw new Error(invalidCard);
         }
-        await this.saveCardMetadata(card);
+        const updated = await this.saveCardMetadata(card);
+        if (!updated)
+            return;
+        // For rank changes, check if path changed (indicating a move)
+        if (isRankChange) {
+            const updatedCard = this.findCard(cardKey);
+            if (updatedCard.path !== previousPath) {
+                this.changeParent(updatedCard, previousParent);
+            }
+        }
     }
     /**
-     * Updates card metadata.
+     * Updates the entire card in the card cache and handles any path/parent changes.
+     * Also persists changes to content and metadata files.
+     * @param card The card with updated information (path, parent, metadata, etc.)
+     */
+    async updateCard(card) {
+        const cachedCard = this.cardCache.getCard(card.key);
+        const pathChange = cachedCard && cachedCard.path !== card.path;
+        if (pathChange) {
+            this.changeParent(card, cachedCard.parent);
+        }
+        const metadataChanged = cachedCard &&
+            JSON.stringify(cachedCard.metadata) !== JSON.stringify(card.metadata);
+        if (metadataChanged) {
+            await this.saveCardMetadata(card);
+        }
+        const contentChanged = cachedCard && cachedCard.content !== card.content;
+        if (contentChanged) {
+            await this.saveCardContent(card);
+        }
+        this.cardCache.updateCard(card.key, card);
+        if (metadataChanged || contentChanged || pathChange) {
+            await this.handleCardChanged(card);
+        }
+    }
+    /**
+     * Updates a card's metadata.
      * @param card affected card
      * @param changedMetadata changed content for the card
      */
     async updateCardMetadata(card, changedMetadata) {
         card.metadata = changedMetadata;
-        return this.saveCardMetadata(card);
+        if (await this.saveCardMetadata(card)) {
+            await this.handleCardChanged(card);
+        }
     }
-    /**
-     * Validates that card's data is valid.
-     * @param card Card to validate.
-     * @returns validation errors, if any
-     */
+    // Validates that card's data is valid.
     async validateCard(card) {
         const invalidCustomData = await this.validator.validateCustomFields(this, card);
-        const invalidWorkFlow = await this.validator.validateWorkflowState(this, card);
-        const invalidLabels = await this.validator.validateCardLabels(card);
+        const invalidWorkFlow = this.validator.validateWorkflowState(this, card);
+        const invalidLabels = this.validator.validateCardLabels(card);
         if (invalidCustomData.length === 0 &&
             invalidWorkFlow.length === 0 &&
             invalidLabels.length === 0) {