@cyberismo/data-handler 0.0.13 → 0.0.15

package/dist/containers/project.d.ts

@@ -19,6 +19,7 @@ import { ProjectPaths } from './project/project-paths.js';
 import { type ResourceName } from '../utils/resource-utils.js';
 import { ResourcesFrom } from './project/resource-collector.js';
 import type { Template } from './template.js';
+import { CalculationResource } from '../resources/calculation-resource.js';
 import { CardTypeResource } from '../resources/card-type-resource.js';
 import { FieldTypeResource } from '../resources/field-type-resource.js';
 import { GraphModelResource } from '../resources/graph-model-resource.js';
@@ -34,27 +35,58 @@ export { ResourcesFrom };
 export declare class Project extends CardContainer {
     private watchResourceChanges?;
     calculationEngine: CalculationEngine;
-    private resources;
+    private createdResources;
+    private logger;
     private projectPaths;
+    private resources;
+    private resourceWatcher;
     private settings;
     private validator;
-    private resourceWatcher;
-    private createdResources;
     constructor(path: string, watchResourceChanges?: boolean | undefined);
-    private replaceCacheValue;
+    private changeParent;
     private findModule;
+    private handleAttachmentChange;
+    private parentFromPath;
+    private removeCachedChildren;
+    private replaceCacheValue;
     private resourcesOfType;
+    private updateCachedChildren;
+    /**
+     * Populate template cards into the card cache.
+     */
+    protected populateTemplateCards(): Promise<void>;
+    /**
+     * Populate both the project cards, and all template cards into card cache.
+     */
+    protected populateCardsCache(): Promise<void>;
     /**
      * Add a given 'resource' to the local resource arrays.
      * @param resource Resource to add.
      * @param data JSON data for the resource.
      */
     addResource(resource: Resource, data: JSON): void;
+    /**
+     * Returns all template cards from the project. This includes all module templates' cards.
+     * @returns all the template cards from the project
+     */
+    allTemplateCards(): Card[];
     /**
      * Returns an array of all the attachments in the project card's (excluding ones in templates).
      * @returns all attachments in the project.
      */
-    attachments(): Promise<CardAttachment[]>;
+    attachments(): CardAttachment[];
+    /**
+     * 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: string): CardAttachment[];
+    /**
+     * Returns all the attachments in the template cards.
+     * @returns all the attachments in the template cards.
+     */
+    attachmentsFromTemplates(): Promise<CardAttachment[]>;
     /**
      * Returns an array of all the calculation files (*.lp) in the project.
      * @param from Defines where resources are collected from.
@@ -62,52 +94,64 @@ export declare class Project extends CardContainer {
      */
     calculations(from?: ResourcesFrom): Promise<Resource[]>;
     /**
-     * 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.
      */
-    cardAttachmentFolder(cardKey: string): Promise<string>;
+    cardAttachmentFolder(cardKey: string): string;
     /**
-     * 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.
+     * 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
      */
-    cardDetailsById(cardKey: string, cardDetails: ProjectFetchCardDetails): Promise<Card | undefined>;
+    createCardAttachment(cardKey: string, attachmentName: string, attachmentData: string | Buffer): Promise<void>;
     /**
-     * Returns path to card's folder.
+     * 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.
+     */
+    removeCardAttachment(cardKey: string, fileName: string): Promise<void>;
+    /**
+     * Returns path to a card's folder.
      * @param cardKey card key
-     * @returns path to card's folder.
+     * @returns path to a card's folder.
      */
     cardFolder(cardKey: string): Promise<string>;
     /**
-     * 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: string): {
-        cardKey: string | undefined;
-        parents: (string | undefined)[];
-        prefix: string;
-        template: string;
-    };
-    /**
-     * 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.
+     * 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: string[]): Card[];
+    /**
+     * 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(): import("./project/card-cache.js").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.
      */
-    cards(path?: string, details?: FetchCardDetails): Promise<Card[]>;
+    cards(path?: string, details?: FetchCardDetails): Card[];
     /**
      * Returns an array of all the card types in the project.
      * @param from Defines where resources are collected from.
      * @returns array of all card types in the project.
      */
     cardTypes(from?: ResourcesFrom): Promise<Resource[]>;
+    /**
+     * 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: Card): Card[];
     /**
      * Updates all local resources.
      */
@@ -115,7 +159,7 @@ export declare class Project extends CardContainer {
     /**
      * Updates all imported module resources.
      */
-    collectModuleResources(): Promise<void>;
+    collectModuleResources(): void;
     /**
      * Returns project configuration.
      * @returns project configuration.
@@ -149,7 +193,7 @@ export declare 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.
      */
-    findSpecificCard(cardToFind: string, details?: ProjectFetchCardDetails): Promise<Card | undefined>;
+    findCard(cardToFind: string, details?: ProjectFetchCardDetails): Card;
     /**
      * Returns an array of all the graph models in the project.
      * @param from Defines where resources are collected from.
@@ -171,36 +215,30 @@ export declare class Project extends CardContainer {
      * When cards are removed.
      * @param deletedCard Card that is to be removed.
      */
-    handleDeleteCard(deletedCard: Card): Promise<void>;
+    handleCardDeleted(deletedCard: Card): Promise<void>;
+    /**
+     * When card is moved.
+     * @param movedCard Card that moved
+     * @param newParentCard New parent for the 'movedCard'
+     * @param oldParentCard Previous parent of the 'movedCard'
+     */
+    handleCardMoved(movedCard: Card, newParentCard?: Card, oldParentCard?: Card): Promise<void>;
     /**
      * When new cards are added.
      * @param cards Added cards.
      */
     handleNewCards(cards: Card[]): Promise<void>;
-    /**
-     * 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: string): boolean;
     /**
      * Adds a module from project.
-     * @param module Name of the module
+     * @param module Module to add
      */
     importModule(module: ModuleSetting): Promise<void>;
     /**
-     * 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: string): boolean;
-    /**
-     * 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
-     */
-    isTemplateCard(cardKey: string): Promise<boolean>;
     /**
      * Returns an array of all the link types in the project.
      * @param from Defines where resources are collected from.
@@ -211,7 +249,7 @@ export declare 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.
      */
     listCards(cardsFrom?: CardLocation): Promise<CardListContainer[]>;
     /**
@@ -224,7 +262,7 @@ export declare class Project extends CardContainer {
     /**
      * 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.
      */
     module(moduleName: string): Promise<ModuleContent | undefined>;
     /**
@@ -254,11 +292,9 @@ export declare class Project extends CardContainer {
      */
     get paths(): 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: string): string;
+    populateCaches(): Promise<void>;
     /**
      * Returns project name.
      */
@@ -274,6 +310,16 @@ export declare class Project extends CardContainer {
      *        Make it use cached value that is only changed when  module is removed/imported.
      */
     projectPrefixes(): Promise<string[]>;
+    /**
+     * Removes a module from the project
+     * @param module Module (name) to remove.
+     */
+    removeModule(moduleName: string): Promise<void>;
+    /**
+     * Removes a resource from Project.
+     * @param resource Resource to remove.
+     */
+    removeResource(resource: Resource): void;
     /**
      * Array of reports in the project.
      * @param from Defines where resources are collected from.
@@ -286,17 +332,12 @@ export declare class Project extends CardContainer {
      * @returns handlebar files from reports.
      */
     reportHandlerBarFiles(from?: ResourcesFrom): Promise<string[]>;
-    /**
-     * Removes a resource from Project.
-     * @param resource Resource to remove.
-     */
-    removeResource(resource: Resource): void;
     /**
      * Returns metadata from a given resource
      * @param name Name of a resource
      * @returns Metadata from the resource.
      */
-    resource<Type>(name: string): Promise<Type | undefined>;
+    resource<Type>(name: string): Type | undefined;
     /**
      * Returns resource cache.
      */
@@ -317,7 +358,7 @@ export declare class Project extends CardContainer {
      * @throws if called with unsupported resource type.
      * @returns Created resource.
      */
-    static resourceObject(project: Project, name: ResourceName): CardTypeResource | FieldTypeResource | GraphModelResource | GraphViewResource | LinkTypeResource | ReportResource | TemplateResource | WorkflowResource;
+    static resourceObject(project: Project, name: ResourceName): CalculationResource | CardTypeResource | FieldTypeResource | GraphModelResource | GraphViewResource | LinkTypeResource | ReportResource | TemplateResource | WorkflowResource;
     /**
      * Shows details of a project.
      * @returns details of a project.
@@ -327,20 +368,13 @@ export declare class Project extends CardContainer {
      * Show cards of a project.
      * @returns an array of all project cards in the project.
      */
-    showProjectCards(): Promise<Card[]>;
-    /**
-     * 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
-     */
-    allTemplateCards(cardDetails?: FetchCardDetails): Promise<Card[]>;
+    showProjectCards(): Card[];
     /**
      * 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.
      */
-    templateCards(templateName: string, cardDetails?: FetchCardDetails): Promise<Card[]>;
+    templateCards(templateName: string): Card[];
     /**
      * Array of templates in the project.
      * @param from Defines where resources are collected from.
@@ -348,8 +382,8 @@ export declare class Project extends CardContainer {
      */
     templates(from?: ResourcesFrom): Promise<Resource[]>;
     /**
-     * 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
      */
     updateCardContent(cardKey: string, content: string): Promise<void>;
@@ -361,17 +395,18 @@ export declare class Project extends CardContainer {
      */
     updateCardMetadataKey(cardKey: string, changedKey: string, newValue: MetadataContent): Promise<void>;
     /**
-     * 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.)
+     */
+    updateCard(card: Card): Promise<void>;
+    /**
+     * Updates a card's metadata.
      * @param card affected card
      * @param changedMetadata changed content for the card
      */
     updateCardMetadata(card: Card, changedMetadata: CardMetadata): Promise<void>;
-    /**
-     * Validates that card's data is valid.
-     * @param card Card to validate.
-     * @returns validation errors, if any
-     */
-    validateCard(card: Card): Promise<string>;
+    private validateCard;
     /**
      * Array of workflows in the project.
      * @param from Defines where resources are collected from.