@cyberismo/data-handler 0.0.14 → 0.0.16

package/src/containers/template.ts

@@ -13,8 +13,8 @@
 
 // node
 import { basename, join, resolve, sep } from 'node:path';
-import { copyFile, mkdir, readdir, rm, writeFile } from 'node:fs/promises';
 import { type Dirent, readdirSync } from 'node:fs';
+import { copyFile, mkdir, rm, writeFile } from 'node:fs/promises';
 
 // Base class
 import { CardContainer } from './card-container.js';
@@ -23,11 +23,7 @@ import {
   type Card,
   type CardAttachment,
   CardNameRegEx,
-  type FetchCardDetails,
-  type FileContentType,
-  type Resource,
 } from '../interfaces/project-interfaces.js';
-import type { CardType, Workflow } from '../interfaces/resource-interfaces.js';
 import { pathExists, stripExtension } from '../utils/file-utils.js';
 import { DefaultContent } from '../resources/create-defaults.js';
 
@@ -38,14 +34,21 @@ import {
   sortItems,
 } from '../utils/lexorank.js';
 import { getChildLogger } from '../utils/log-utils.js';
-import { readJsonFile } from '../utils/json.js';
+import { isModulePath } from '../utils/card-utils.js';
 import { Project } from './project.js';
 import { resourceName } from '../utils/resource-utils.js';
 
+import { ROOT } from '../utils/constants.js';
+
+// @todo: Fix the constructor to not use Resource.
+import type { Resource } from './project/resource-cache.js';
+
 // creates template instance based on a project path and name
 export class Template extends CardContainer {
+  private templateName: string;
   private templatePath: string;
   private templateCardsPath: string;
+  private fullTemplateName: string; // Full template name from resource (e.g., 'test/templates/page')
   private project: Project;
   private get logger() {
     return getChildLogger({
@@ -53,12 +56,19 @@ export class Template extends CardContainer {
     });
   }
 
+  /**
+   * Creates an instance of Template container that holds template related cards.
+   * @param project Project in which template is.
+   * @param template Template resource that this container is connected to.
+   */
+  // @todo: Fix the constructor to not use Resource, but resource full path
   constructor(project: Project, template: Resource) {
     // Templates might come from modules. Remove module name from template name.
     const templateName = stripExtension(basename(template.name));
-    super(template.path!, templateName);
+    super(template.path, project.projectPrefix, templateName);
+    this.templateName = templateName;
+    this.fullTemplateName = template.name;
 
-    // prevent constructing a new project object, if one is passed to this class.
     this.project = project;
     // optimization - if template.path is set - use it
     this.templatePath =
@@ -68,30 +78,6 @@ export class Template extends CardContainer {
     this.templateCardsPath = join(this.templatePath, 'c');
   }
 
-  // Fetches project top level cards only.
-  // Top level cards are those that have parent as 'root'.
-  // todo: This should be in 'project' or 'card-container'
-  private async rootLevelProjectCards(): Promise<Card[]> {
-    const entries = (
-      await readdir(this.project.paths.cardRootFolder, {
-        withFileTypes: true,
-      })
-    ).filter((entry) => entry.isDirectory() && CardNameRegEx.test(entry.name));
-    const cardPromises = entries.map(async (entry) => {
-      const currentPath = join(entry.parentPath, entry.name);
-      return {
-        key: entry.name,
-        path: currentPath,
-        metadata: await readJsonFile(
-          join(currentPath, CardContainer.cardMetadataFile),
-        ),
-        children: [],
-        attachments: [],
-      };
-    });
-    return Promise.all(cardPromises);
-  }
-
   // Creates card(s) as project cards from template.
   private async doCreateCards(
     cards: Card[],
@@ -110,13 +96,13 @@ export class Template extends CardContainer {
 
       // Handle ranking for parent cards
       const parentCards = sortItems(
-        cards.filter((c) => c.parent === 'root'),
+        cards.filter((c) => c.parent === ROOT),
         (c) => c?.metadata?.rank || '',
       );
 
       const futureSiblings = parentCard
-        ? parentCard.children || []
-        : await this.rootLevelProjectCards();
+        ? this.project.cardKeysToCards(parentCard.children)
+        : this.rootLevelProjectCards();
 
       let latestRank =
         sortItems(
@@ -165,6 +151,24 @@ export class Template extends CardContainer {
       }
 
       card.key = templateIDMap.get(card.key) || card.key;
+
+      // Set parent field based on template hierarchy and creation location
+      // Store the original template parent before key remapping
+      const originalParentKey = card.parent;
+
+      if (parentCard) {
+        if (!originalParentKey || originalParentKey === ROOT) {
+          card.parent = parentCard.key;
+        } else {
+          card.parent = templateIDMap.get(originalParentKey) || parentCard.key;
+        }
+      } else {
+        if (!originalParentKey || originalParentKey === ROOT) {
+          card.parent = ROOT;
+        } else {
+          card.parent = templateIDMap.get(originalParentKey) || ROOT;
+        }
+      }
     };
 
     // Process attachments
@@ -202,20 +206,14 @@ export class Template extends CardContainer {
     // Process metadata
     const processMetadata = async (card: Card, parentCards: Card[]) => {
       if (!card.metadata) return card;
+      const cardType = this.project.resources
+        .byType(card.metadata?.cardType, 'cardTypes')
+        .show();
 
-      const cardType = await this.project.resource<CardType>(
-        card.metadata.cardType || '',
-      );
-      if (!cardType) {
-        throw new Error(
-          `Card type '${card.metadata.cardType}' of card ${card.key} cannot be found`,
-        );
-      }
+      const workflow = this.project.resources
+        .byType(cardType.workflow, 'workflows')
+        .show();
 
-      const workflow = await this.project.resource<Workflow>(cardType.workflow);
-      if (!workflow) {
-        throw new Error(`Workflow '${cardType.workflow}' cannot be found`);
-      }
       const initialWorkflowState = workflow.transitions.find(
         (item) => item.fromState.includes('') || item.fromState.length === 0,
       );
@@ -256,8 +254,10 @@ export class Template extends CardContainer {
       const templatesFolder = this.templateFolder();
 
       // Process all cards in parallel
+      // Create deep copies to avoid mutating the cached template cards
       const processedCards = await Promise.all(
-        cards.map(async (card) => {
+        cards.map(async (originalCard) => {
+          const card: Card = structuredClone(originalCard);
           // Update paths and keys
           updateCardPaths(card, templateIDMap, templatesFolder);
 
@@ -271,7 +271,7 @@ export class Template extends CardContainer {
           await mkdir(processedCard.path, { recursive: true });
 
           await Promise.all([
-            processedCard.metadata && this.saveCardMetadata(processedCard),
+            this.saveCardMetadata(processedCard),
             writeFile(
               join(processedCard.path, Project.cardContentFile),
               processedAttachments.content || '',
@@ -280,16 +280,25 @@ export class Template extends CardContainer {
           return processedCard;
         }),
       );
+      await this.project.handleNewCards(processedCards);
       return processedCards;
     } catch (error) {
       await this.removeCards(templateIDMap);
-      if (error instanceof Error) {
-        throw new Error(`Failed to create cards: ${error.message}`);
-      }
+      this.logger.error({ error }, 'Failed to create cards');
       throw error;
     }
   }
 
+  // Helper method to find a card.
+  private findCardDirect(cardKey: string): Card {
+    const allCards = this.cards();
+    const result = allCards.find((card) => card.key === cardKey);
+    if (!result) {
+      throw new Error(`Card '${cardKey}' is not part of template`);
+    }
+    return result;
+  }
+
   // fetches path to module.
   private moduleTemplatePath(templateName: string): string {
     // If template path has already been deduced, return it.
@@ -313,6 +322,7 @@ export class Template extends CardContainer {
       );
       const exists = pathExists(templateFolderInModule);
       if (exists) {
+        this.templatePath = templateFolderInModule;
         return templateFolderInModule;
       }
     }
@@ -320,16 +330,14 @@ export class Template extends CardContainer {
   }
 
   // Removes cards
+  // Helper for doCreateCards; not intended for any other use.
   private async removeCards(cardMap: Map<string, string>) {
-    const tasks: Promise<Card | undefined>[] = [];
+    const cards: Card[] = [];
     // Find all cards that need to be removed.
     cardMap.forEach((createdCard) => {
-      tasks.push(this.project.findSpecificCard(createdCard));
+      const card = this.project.findCard(createdCard);
+      cards.push(card);
     });
-    // Remove empty results.
-    const cards = (await Promise.all(tasks)).filter(
-      (item) => item !== undefined,
-    );
     // Delete card folders.
     const deleteAll: Promise<void>[] = [];
     cards.forEach((card) => {
@@ -338,6 +346,14 @@ export class Template extends CardContainer {
     await Promise.all(deleteAll);
   }
 
+  // Fetches project top level cards only.
+  private rootLevelProjectCards(): Card[] {
+    const allProjectCards = this.project.cards(
+      this.project.paths.cardRootFolder,
+    );
+    return allProjectCards.filter((card) => card.parent === ROOT);
+  }
+
   // Set path to template location.
   private setTemplatePath(templateName: string): string {
     const { prefix, identifier } = resourceName(templateName);
@@ -376,19 +392,20 @@ export class Template extends CardContainer {
     parentCard?: Card,
   ): Promise<string> {
     const destinationCardPath = parentCard
-      ? join(await this.cardFolder(parentCard.key), 'c')
+      ? join(this.cardFolder(parentCard.key), 'c')
       : this.templateCardsPath;
     let newCardKey = '';
 
     try {
+      // todo: to use cache instead of file access
       if (!pathExists(this.templateFolder())) {
         throw new Error(`Template '${this.containerName}' does not exist`);
       }
-      const cardType = await this.project.resource<CardType>(cardTypeName);
-      if (cardType === undefined) {
-        throw new Error(`Card type '${cardTypeName}' does not exist`);
-      }
-      if (parentCard && !this.hasCard(parentCard.key)) {
+      const cardType = this.project.resources
+        .byType(cardTypeName, 'cardTypes')
+        .show();
+
+      if (parentCard && !this.hasTemplateCard(parentCard.key)) {
         throw new Error(
           `Card '${parentCard.key}' does not exist in template '${this.containerName}'`,
         );
@@ -401,8 +418,8 @@ export class Template extends CardContainer {
         : join(this.templateCardsPath, newCardKey);
 
       const templateCards = parentCard
-        ? parentCard.children || []
-        : await this.cards();
+        ? this.project.cardKeysToCards(parentCard.children)
+        : this.cards();
       const defaultContent = DefaultContent.card(cardType, templateCards);
 
       await mkdir(templateCardToCreate, { recursive: true });
@@ -413,12 +430,13 @@ export class Template extends CardContainer {
         children: [],
         attachments: [],
         content: '',
+        parent: parentCard ? parentCard.key : ROOT,
       };
       await this.saveCard(defaultCard);
+      await this.project.handleNewCards([defaultCard]);
     } catch (error) {
-      if (error instanceof Error) {
-        throw new Error(error.message);
-      }
+      this.logger.error({ error });
+      throw error;
     }
     return newCardKey;
   }
@@ -427,8 +445,8 @@ export class Template extends CardContainer {
    * Return all attachment in the template.
    * @returns all attachments in the template.
    */
-  public async attachments(): Promise<CardAttachment[]> {
-    return super.attachments(this.templateCardsPath);
+  public attachments(): CardAttachment[] {
+    return this.project.attachmentsByPath(this.templateCardsPath);
   }
 
   /**
@@ -436,58 +454,37 @@ export class Template extends CardContainer {
    * @param cardKey card key
    * @returns path to card's attachment folder.
    */
-  public async cardAttachmentFolder(cardKey: string): Promise<string> {
-    const pathToCard = await this.cardFolder(cardKey);
-    if (!pathToCard) {
-      throw new Error(`Template card '${cardKey}' not found`);
-    }
+  public cardAttachmentFolder(cardKey: string): string {
+    const pathToCard = this.project.findCard(cardKey)?.path;
     return join(pathToCard, 'a');
   }
 
-  /**
-   * 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.
-   */
-  public async cardDetailsById(
-    cardKey: string,
-    cardDetails: FetchCardDetails,
-  ): Promise<Card | undefined> {
-    return super.findCard(this.templateCardsPath, cardKey, cardDetails);
-  }
-
   /**
    * returns path to card's folder.
    * @param cardKey card key
    * @returns path to card's folder.
    */
-  public async cardFolder(cardKey: string): Promise<string> {
-    const found = await super.findCard(this.templateCardsPath, cardKey);
+  public cardFolder(cardKey: string): string {
+    const found = this.findCardDirect(cardKey);
     return found ? found.path : '';
   }
 
   /**
-   * Returns all cards in the template. Cards have content and metadata.
+   * Returns all cards in the template.
    * @param placeHolderPath This is not used. Needed to be compatible with base class.
-   * @param details Optional. Which details are returned for each card. If missing, default value will be used.
    * @returns Template cards in the template.
    */
-  public async cards(
-    placeHolderPath?: string,
-    details?: FetchCardDetails,
-  ): Promise<Card[]> {
+  public cards(placeHolderPath?: string): Card[] {
     if (placeHolderPath) {
       this.logger.warn('A non-used variable was used in the cards method');
     }
-    const cardDetails = details
-      ? details
-      : {
-          content: true,
-          contentType: 'adoc' as FileContentType,
-          metadata: true,
-        };
-    return super.cards(this.templateCardsPath, cardDetails);
+
+    // Filter cards from the project's card cache that belong to this template.
+    const allCards = [...this.project.cardsCache.getCards()];
+    return allCards.filter(
+      (card) =>
+        card.location !== 'project' && card.location === this.fullTemplateName,
+    );
   }
 
   /**
@@ -496,13 +493,7 @@ export class Template extends CardContainer {
    * @returns array of created card keys
    */
   public async createCards(parentCard?: Card): Promise<Card[]> {
-    const cards = await this.cards('', {
-      content: true,
-      contentType: 'adoc',
-      metadata: true,
-      attachments: true,
-      parent: true,
-    });
+    const cards = this.cards();
     if (cards.length === 0) {
       throw new Error(
         `No cards in template '${this.containerName}'. Please add template cards with 'add' command first.`,
@@ -514,13 +505,9 @@ export class Template extends CardContainer {
   /**
    * Returns specific card.
    * @param cardKey Card key to find from template.
-   * @param details Card details to include in return value.
    * @returns specific card details
    */
-  public async findSpecificCard(
-    cardKey: string,
-    details: FetchCardDetails = {},
-  ): Promise<Card | undefined> {
+  public findCard(cardKey: string): Card {
     const cardPrefix = cardKey.split('_').at(0);
     const moduleCardFromProject =
       this.basePath.includes('local') &&
@@ -530,18 +517,19 @@ export class Template extends CardContainer {
       this.project.projectPrefix === cardPrefix;
     // If the result is impossible, return undefined.
     if (moduleCardFromProject || projectCardFromModule) {
-      return undefined;
+      throw new Error(`Card '${cardKey}' is not part of template`);
     }
-    return super.findCard(this.templateCardsPath, cardKey, details);
+
+    return this.findCardDirect(cardKey);
   }
 
   /**
    * Checks if a specific card key exists in a template.
    * @param cardKey Card key to find from template.
-   * @return true if card with a given card key exists in the template, false otherwise.
+   * @returns true if card with a given card key exists in the template, false otherwise.
    */
-  public hasCard(cardKey: string): boolean {
-    return super.hasCard(cardKey, this.templateCardsPath);
+  public hasTemplateCard(cardKey: string): boolean {
+    return this.project.hasTemplateCard(cardKey);
   }
 
   /**
@@ -549,15 +537,30 @@ export class Template extends CardContainer {
    * @returns true, if template is exists in project; false otherwise
    */
   public isCreated(): boolean {
+    // todo: to use cache instead of file access
     return pathExists(this.templateCardsPath);
   }
 
   /**
-   * Returns an array of all the cards in the project. Cards don't have content nor metadata.
-   * @returns all cards in the project.
+   * Returns an array of all the cards in the template.
+   * @returns all cards in the template.
    */
-  public async listCards(): Promise<Card[]> {
-    return super.cards(this.templateCardsPath);
+  public listCards(): Card[] {
+    // Construct the full template name to match what's stored in cache
+    const fullTemplateName = isModulePath(this.basePath)
+      ? `${this.basePath.split(`${sep}modules${sep}`)[1].split(`${sep}templates`)[0]}/templates/${this.templateName}`
+      : `${this.project.projectPrefix}/templates/${this.templateName}`;
+
+    const templateCards = Array.from(this.project.cardsCache.getCards()).filter(
+      (cachedCard) => {
+        if (cachedCard.location === 'project') {
+          return false;
+        }
+        const storedTemplateName = cachedCard.location;
+        return storedTemplateName === fullTemplateName;
+      },
+    );
+    return templateCards;
   }
 
   /**
@@ -568,14 +571,6 @@ export class Template extends CardContainer {
     return this.templateCardsPath;
   }
 
-  /**
-   * Path to template configuration json file.
-   * @returns path to the template's configuration file.
-   */
-  public templateConfigurationFilePath(): string {
-    return join(this.templatePath, '..', this.containerName + '.json');
-  }
-
   /**
    * Returns path to 'templates' folder.
    * @returns path to the project's folder that contains templates.
@@ -583,12 +578,4 @@ export class Template extends CardContainer {
   public templateFolder(): string {
     return this.templatePath;
   }
-
-  /**
-   * Show cards of a template with hierarchy structure.
-   * @returns an array of all template cards with proper parent-child relationships.
-   */
-  public async showTemplateCards(): Promise<Card[]> {
-    return this.showCards(this.templateCardsPath);
-  }
 }

package/src/index.ts

@@ -20,6 +20,7 @@ import {
 } from './command-handler.js';
 import { Validate } from './commands/validate.js';
 export * from './interfaces/project-interfaces.js';
+export * from './interfaces/macros.js';
 import { requestStatus } from './interfaces/request-status-interfaces.js';
 import { UpdateOperations } from './resources/resource-object.js';
 export type {

package/src/interfaces/folder-content-interfaces.ts

@@ -13,6 +13,8 @@
 
 import type { Schema } from 'jsonschema';
 
+export type { Schema };
+
 // All file mappings for lookup (filename -> property name)
 export const ALL_FILE_MAPPINGS = {
   'calculation.lp': 'calculation',
@@ -24,7 +26,7 @@ export const ALL_FILE_MAPPINGS = {
 } as const;
 
 // Reverse mappings from property names to filenames
-export const REVERSE_FILE_MAPPINGS = {
+export const CONTENT_FILES = {
   calculation: 'calculation.lp',
   contentTemplate: 'index.adoc.hbs',
   model: 'model.lp',
@@ -34,7 +36,7 @@ export const REVERSE_FILE_MAPPINGS = {
 } as const;
 
 // Union type of all valid content property names
-export type ContentPropertyName = keyof typeof REVERSE_FILE_MAPPINGS;
+export type ContentPropertyName = keyof typeof CONTENT_FILES;
 
 // Content interface for Calculation resources
 export interface CalculationContent {
@@ -43,12 +45,13 @@ export interface CalculationContent {
 
 // Content interface for Graph Model resources
 export interface GraphModelContent {
-  model?: string;
+  model: string;
 }
 
 // Content interface for Graph View resources
 export interface GraphViewContent {
   viewTemplate?: string;
+  schema?: Schema;
 }
 
 // Content interface for Report resources
@@ -58,15 +61,19 @@ export interface ReportContent {
   schema?: Schema;
 }
 
+export type FolderResourceContent =
+  | CalculationContent
+  | GraphModelContent
+  | GraphViewContent
+  | ReportContent;
+
 /**
  * Get filename with property name
  * @param propertyName Property name.
  * @returns filename that matches property name
  */
 export function filename(propertyName: string): string | undefined {
-  return REVERSE_FILE_MAPPINGS[
-    propertyName as keyof typeof REVERSE_FILE_MAPPINGS
-  ];
+  return CONTENT_FILES[propertyName as keyof typeof CONTENT_FILES];
 }
 
 /**
@@ -74,7 +81,7 @@ export function filename(propertyName: string): string | undefined {
  * @param filename Filename.
  * @returns property name that matches filename
  */
-export function propertyName(
+export function contentPropertyName(
   filename: string,
 ): ContentPropertyName | undefined {
   return ALL_FILE_MAPPINGS[filename as keyof typeof ALL_FILE_MAPPINGS];

package/src/interfaces/macros.ts

@@ -59,3 +59,5 @@ export interface HandlebarsOptions {
 }
 
 export type MacroName = keyof typeof macroMetadata;
+
+export * from '../macros/types.js';

package/src/interfaces/project-interfaces.ts

@@ -21,8 +21,14 @@ export interface Card {
   content?: string;
   metadata?: CardMetadata;
   parent?: string;
-  children: Card[];
+  children: string[];
   attachments: CardAttachment[];
+  calculations?: unknown[];
+}
+
+// Single card, but childrenCards as Card array
+export interface CardWithChildrenCards extends Card {
+  childrenCards: CardWithChildrenCards[];
 }
 
 // Attachment details
@@ -172,6 +178,7 @@ export interface ProjectMetadata {
 
 // Project's settings (=cardsConfig.json).
 export interface ProjectSettings {
+  schemaVersion?: number;
   cardKeyPrefix: string;
   name: string;
   modules: ModuleSetting[];
@@ -222,12 +229,9 @@ export type RemovableResourceTypes =
   | 'workflow'
   | 'label';
 
-// Project resource, such as workflow, template or card type as file system object.
-export interface Resource {
-  name: string;
-  path: string;
-}
-
+// TODO: fix terminology. In DH, modules are not resources.
+// Also, this contains non-folder resources
+// This was done likely like this, because on the CLI, they act similarly to resources
 // Resources that have own folders.
 export type ResourceFolderType =
   | 'calculations'
@@ -241,6 +245,9 @@ export type ResourceFolderType =
   | 'templates'
   | 'workflows';
 
+// This covers all 'true' resources
+export type ResourceType = Exclude<ResourceFolderType, 'modules'>;
+
 // All resource types; both singular and plural.
 export type ResourceTypes =
   | RemovableResourceTypes