@cyberismo/data-handler 0.0.2

package/dist/containers/project.d.ts

@@ -0,0 +1,351 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import { CardContainer } from './card-container.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 { 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 type { Template } from './template.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 };
+/**
+ * Represents project folder.
+ */
+export declare class Project extends CardContainer {
+    private resources;
+    private projectPaths;
+    private settings;
+    private validator;
+    private createdResources;
+    constructor(path: string);
+    private findModule;
+    private resourcesOfType;
+    /**
+     * Add a given 'resource' to the local resource arrays.
+     * @param resource Resource to add.
+     */
+    addResource(resource: Resource, data: JSON): void;
+    /**
+     * 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[]>;
+    /**
+     * 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.
+     */
+    calculations(from?: ResourcesFrom): Promise<Resource[]>;
+    /**
+     * Returns path to card's attachment folder.
+     * @param cardKey card key
+     * @returns path to card's attachment folder.
+     */
+    cardAttachmentFolder(cardKey: string): Promise<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.
+     */
+    cardDetailsById(cardKey: string, cardDetails: ProjectFetchCardDetails): Promise<Card | undefined>;
+    /**
+     * Returns path to card's folder.
+     * @param cardKey card key
+     * @returns path to 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
+     * 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.
+     */
+    cards(path?: string, details?: FetchCardDetails): Promise<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[]>;
+    /**
+     * Updates all local resources.
+     */
+    collectLocalResources(): void;
+    /**
+     * Updates all imported module resources.
+     */
+    collectModuleResources(): Promise<void>;
+    /**
+     * Returns project configuration.
+     * @returns project configuration.
+     */
+    get configuration(): ProjectConfiguration;
+    /**
+     * Creates a Template object from template Card. It is ensured that the template is part of project.
+     * @param card Card that is part of some template.
+     * @returns Template object, or undefined if card is not part of template.
+     */
+    createTemplateObjectFromCard(card: Card): Template | undefined;
+    /**
+     * 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[]>;
+    /**
+     * 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.
+     */
+    graphViews(from?: ResourcesFrom): Promise<Resource[]>;
+    /**
+     * 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 moduleName Name of the module
+     */
+    importModule(module: ModuleSetting): Promise<void>;
+    /**
+     * Checks if 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?
+     */
+    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 includeCardsFrom Where to return cards from (project, templates, or both)
+     * @returns all cards in the project.
+     */
+    listCards(cardsFrom?: CardLocation): Promise<CardListContainer[]>;
+    /**
+     * Return cardIDs of the cards in the project or from templates, or both.
+     * @param includeCardsFrom Where to return cards from (project, templates, or both)
+     * @returns Array of cardIDs.
+     * @note that cardIDs are not sorted.
+     */
+    listCardIds(cardsFrom?: CardLocation): Promise<Set<string>>;
+    /**
+     * Returns details of a certain module.
+     * @param moduleName Name of the module.
+     * @returns module details, or undefined if workflow 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)
+     * @returns a new card key string
+     * @throws if a unique key could not be created within set number of attempts
+     */
+    newCardKey(cardIds: Set<string>): string;
+    /**
+     * Returns an array of new unique card keys with project prefix (e.g. test_x649it4x).
+     * Random part of string will be always 8 characters in base-36 (0-9a-z)
+     * @returns an array of new card key strings
+     * @throws if a unique key could not be created within set number of attempts
+     */
+    newCardKeys(keysToCreate: number, cardIds: Set<string>): string[];
+    /**
+     * Getter. Returns a class that handles the project's paths.
+     */
+    get paths(): ProjectPaths;
+    /**
+     * Returns full path to a given card.
+     * @param cardKey card to check path for.
+     * @returns path to a given card.
+     */
+    pathToCard(cardKey: string): string;
+    /**
+     * Getter. Returns project name.
+     */
+    get projectName(): string;
+    /**
+     * Getter. Returns project prefix.
+     */
+    get projectPrefix(): string;
+    /**
+     * Collects all prefixes used in the project (project's own plus all from 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[]>;
+    /**
+     * Removes a module from project.
+     * @param moduleName Name of the module
+     */
+    removeModule(moduleName: string): Promise<void>;
+    /**
+     * 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;
+    /**
+     * Returns metadata from a given resource
+     * @param name Name of a resource
+     * @returns Metadata from the resource.
+     */
+    resource<Type>(name: string): Promise<Type | undefined>;
+    get resourceCache(): Map<string, JSON>;
+    /**
+     * 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.
+     */
+    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): LinkTypeResource | CardTypeResource | FieldTypeResource | GraphModelResource | GraphViewResource | ReportResource | TemplateResource | WorkflowResource;
+    /**
+     * Shows details of a project.
+     * @returns details of a project.
+     */
+    show(): Promise<ProjectMetadata>;
+    /**
+     * 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[]>;
+    /**
+     * Returns cards from single template.
+     * @param templateName Name of the template
+     * @param cardDetails Card information
+     * @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[]>;
+    /**
+     * Update card content.
+     * @param cardKey card's ID that is updated.
+     * @param content changed content
+     */
+    updateCardContent(cardKey: string, content: string): Promise<void>;
+    /**
+     * Updates card metadata's single key.
+     * @param cardKey card that is updated.
+     * @param changedKey changed metadata key
+     * @param newValue changed value for the key
+     */
+    updateCardMetadataKey(cardKey: string, changedKey: string, newValue: MetadataContent): Promise<void>;
+    /**
+     * Updates card 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.
+     */
+    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[]>;
+}