@cyberismo/data-handler 0.0.14 → 0.0.16

package/dist/containers/project.d.ts

@@ -13,110 +13,113 @@
 */
 import { CardContainer } from './card-container.js';
 import { CalculationEngine } from './project/calculation-engine.js';
-import { type Card, type CardAttachment, CardLocation, type CardListContainer, type CardMetadata, type FetchCardDetails, type MetadataContent, type ModuleContent, type ModuleSetting, type ProjectFetchCardDetails, type ProjectMetadata, type Resource, type ResourceFolderType } from '../interfaces/project-interfaces.js';
+import { type Card, type CardAttachment, CardLocation, type CardListContainer, type CardMetadata, type FetchCardDetails, type MetadataContent, type ModuleContent, type ModuleSetting, type ProjectFetchCardDetails, type ProjectMetadata } from '../interfaces/project-interfaces.js';
 import { ProjectConfiguration } from '../project-settings.js';
 import { ProjectPaths } from './project/project-paths.js';
-import { type ResourceName } from '../utils/resource-utils.js';
-import { ResourcesFrom } from './project/resource-collector.js';
+import { ResourcesFrom } from './project/resource-cache.js';
+import { ResourceHandler } from './project/resource-handler.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';
-import { GraphViewResource } from '../resources/graph-view-resource.js';
-import { LinkTypeResource } from '../resources/link-type-resource.js';
-import { ReportResource } from '../resources/report-resource.js';
-import { TemplateResource } from '../resources/template-resource.js';
-import { WorkflowResource } from '../resources/workflow-resource.js';
 export { ResourcesFrom };
+/**
+ * Options for Project initialization.
+ * autoSave - If project configuration changes are saved automatically. Default true.
+ * watchResourceChanges - If project refresh automatically to filesystem changes. Default false.
+ */
+export interface ProjectOptions {
+    autoSave?: boolean;
+    watchResourceChanges?: boolean;
+}
 /**
  * Represents project folder.
  */
 export declare class Project extends CardContainer {
-    private watchResourceChanges?;
+    private options;
     calculationEngine: CalculationEngine;
-    private resources;
+    private logger;
     private projectPaths;
+    private resourceHandler;
+    private resourceWatcher;
     private settings;
     private validator;
-    private resourceWatcher;
-    private createdResources;
-    constructor(path: string, watchResourceChanges?: boolean | undefined);
-    private replaceCacheValue;
+    constructor(path: string, options?: ProjectOptions);
+    private changeParent;
     private findModule;
-    private resourcesOfType;
+    private handleAttachmentChange;
+    private parentFromPath;
+    private removeCachedChildren;
+    private updateCachedChildren;
+    private validateCard;
+    /**
+     * Populate template cards into the card cache.
+     */
+    protected populateTemplateCards(): Promise<void>;
     /**
-     * Add a given 'resource' to the local resource arrays.
-     * @param resource Resource to add.
-     * @param data JSON data for the resource.
+     * Populate both the project cards, and all template cards into card cache.
      */
-    addResource(resource: Resource, data: JSON): void;
+    protected populateCardsCache(): Promise<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 an array of all the calculation files (*.lp) in the project.
-     * @param from Defines where resources are collected from.
-     * @returns array of all calculation files in the project.
+     * 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
      */
-    calculations(from?: ResourcesFrom): Promise<Resource[]>;
+    attachmentsByPath(path: string): CardAttachment[];
     /**
-     * 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.
+     * 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.
-     * @returns all cards from the given path in the project.
+     * Fetches full Card data for given card keys
+     * @param cardIds array of card keys to fetch
+     * @returns Card data to the given card keys
      */
-    cards(path?: string, details?: FetchCardDetails): Promise<Card[]>;
+    cardKeysToCards(cardIds: string[]): 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.
+     * 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.
      */
-    cardTypes(from?: ResourcesFrom): Promise<Resource[]>;
+    cards(path?: string, details?: FetchCardDetails): Card[];
     /**
-     * Updates all local resources.
+     * 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).
      */
-    collectLocalResources(): void;
+    get cardsCache(): import("./project/card-cache.js").CardCache;
     /**
-     * Updates all imported module resources.
+     * 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
      */
-    collectModuleResources(): Promise<void>;
+    childrenCards(card: Card): Card[];
     /**
      * Returns project configuration.
      * @returns project configuration.
@@ -132,37 +135,19 @@ export declare class Project extends CardContainer {
      * Cleanups project when it is being closed.
      */
     dispose(): void;
-    /**
-     * Returns an array of all the field types in the project.
-     * @param from Defines where resources are collected from.
-     * @returns array of all field types in the project.
-     */
-    fieldTypes(from?: ResourcesFrom): Promise<Resource[]>;
-    /**
-     * Finds root of a project
-     * @param path Path where to start looking for the project root.
-     * @returns path to a project root, or empty string.
-     */
-    static findProjectRoot(path: string): Promise<string>;
     /**
      * Returns specific card.
      * @param cardToFind Card key to find
      * @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>;
-    /**
-     * Returns an array of all the graph models in the project.
-     * @param from Defines where resources are collected from.
-     * @returns array of all the graph models in the project.
-     */
-    graphModels(from?: ResourcesFrom): Promise<Resource[]>;
+    findCard(cardToFind: string, details?: ProjectFetchCardDetails): Card;
     /**
-     * Returns an array of all the graph views in the project.
-     * @param from Defines where resources are collected from.
-     * @returns array of all the graph views in the project.
+     * Finds root of a project
+     * @param path Path where to start looking for the project root.
+     * @returns path to a project root, or empty string.
      */
-    graphViews(from?: ResourcesFrom): Promise<Resource[]>;
+    static findProjectRoot(path: string): Promise<string>;
     /**
      * When card changes.
      * @param changedCard Card that was changed.
@@ -172,47 +157,35 @@ 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.
-     * @returns array of all link types in the project.
-     */
-    linkTypes(from?: ResourcesFrom): Promise<Resource[]>;
     /**
      * 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[]>;
     /**
@@ -225,14 +198,9 @@ 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>;
-    /**
-     * Returns list of modules in the project.
-     * @returns list of modules in the project.
-     */
-    modules(): Promise<Resource[]>;
     /**
      * Returns a new unique card key with project prefix (e.g. test_x649it4x).
      * Random part of string will be always 8 characters in base-36 (0-9a-z)
@@ -255,11 +223,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.
      */
@@ -269,56 +235,28 @@ export declare class Project extends CardContainer {
      */
     get projectPrefix(): string;
     /**
-     * Collects all prefixes used in the project (project's own plus all from modules).
+     * Returns all prefixes used in the project (project's own plus all from imported modules).
      * @returns all prefixes used in the project.
-     * @todo - move the module prefix fetch to resource-collector.
-     *        Make it use cached value that is only changed when  module is removed/imported.
-     */
-    projectPrefixes(): Promise<string[]>;
-    /**
-     * Array of reports in the project.
-     * @param from Defines where resources are collected from.
-     * @returns array of all reports in the project.
-     */
-    reports(from?: ResourcesFrom): Promise<Resource[]>;
-    /**
-     * Returns handlebar files from reports.
-     * @param from Defines where report handlebar files are collected from.
-     * @returns handlebar files from reports.
-     */
-    reportHandlerBarFiles(from?: ResourcesFrom): Promise<string[]>;
-    /**
-     * Removes a resource from Project.
-     * @param resource Resource to remove.
      */
-    removeResource(resource: Resource): void;
+    projectPrefixes(): string[];
     /**
-     * Returns metadata from a given resource
-     * @param name Name of a resource
-     * @returns Metadata from the resource.
+     * 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.
      */
-    resource<Type>(name: string): Promise<Type | undefined>;
+    removeCardAttachment(cardKey: string, fileName: string): Promise<void>;
     /**
-     * Returns resource cache.
+     * Removes a module from the project cache and configuration.
+     * @note that ModuleManager removes the actual files.
+     * @param moduleName Module name to remove.
      */
-    get resourceCache(): Map<string, JSON>;
+    removeModule(moduleName: string): Promise<void>;
     /**
-     * Checks if a given resource exists in the project already.
-     * @param resourceType Type of resource as a string.
-     * @param name Valid name of resource.
-     * @returns boolean, true if resource exists; false otherwise.
+     * Accessor for resource handler.
+     * @returns Resource handler instance.
      */
-    resourceExists(resourceType: ResourceFolderType, name: string): Promise<boolean>;
-    /**
-     * Instantiates resource object from project with a resource name.
-     * @note that this is memory based object only.
-     *       To manipulate the resource (create files, delete files etc), use the resource object's API.
-     * @param project Project from which resources are created from.
-     * @param name Resource name
-     * @throws if called with unsupported resource type.
-     * @returns Created resource.
-     */
-    static resourceObject(project: Project, name: ResourceName): CalculationResource | CardTypeResource | FieldTypeResource | GraphModelResource | GraphViewResource | LinkTypeResource | ReportResource | TemplateResource | WorkflowResource;
+    get resources(): ResourceHandler;
     /**
      * Shows details of a project.
      * @returns details of a project.
@@ -328,29 +266,16 @@ 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[]>;
-    /**
-     * Array of templates in the project.
-     * @param from Defines where resources are collected from.
-     * @returns array of all templates in the project.
-     */
-    templates(from?: ResourcesFrom): Promise<Resource[]>;
+    templateCards(templateName: string): Card[];
     /**
-     * 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>;
@@ -362,21 +287,15 @@ 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>;
-    /**
-     * Array of workflows in the project.
-     * @param from Defines where resources are collected from.
-     * @returns array of all workflows in the project.
-     */
-    workflows(from?: ResourcesFrom): Promise<Resource[]>;
 }