@cyberismo/data-handler 0.0.14 → 0.0.15

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,8 +23,6 @@ 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';
@@ -38,14 +36,18 @@ 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';
+
 // 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({
@@ -56,9 +58,10 @@ export class Template extends CardContainer {
   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 +71,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 +89,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 +144,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
@@ -203,16 +200,14 @@ export class Template extends CardContainer {
     const processMetadata = async (card: Card, parentCards: Card[]) => {
       if (!card.metadata) return card;
 
-      const cardType = await this.project.resource<CardType>(
-        card.metadata.cardType || '',
-      );
+      const cardType = this.project.resource<CardType>(card.metadata?.cardType);
       if (!cardType) {
         throw new Error(
-          `Card type '${card.metadata.cardType}' of card ${card.key} cannot be found`,
+          `Card type '${card.metadata?.cardType}' of card ${card.key} cannot be found`,
         );
       }
 
-      const workflow = await this.project.resource<Workflow>(cardType.workflow);
+      const workflow = this.project.resource<Workflow>(cardType.workflow);
       if (!workflow) {
         throw new Error(`Workflow '${cardType.workflow}' cannot be found`);
       }
@@ -256,8 +251,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);
 
@@ -280,16 +277,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 +319,7 @@ export class Template extends CardContainer {
       );
       const exists = pathExists(templateFolderInModule);
       if (exists) {
+        this.templatePath = templateFolderInModule;
         return templateFolderInModule;
       }
     }
@@ -320,16 +327,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 +343,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);
@@ -384,11 +397,11 @@ export class Template extends CardContainer {
       if (!pathExists(this.templateFolder())) {
         throw new Error(`Template '${this.containerName}' does not exist`);
       }
-      const cardType = await this.project.resource<CardType>(cardTypeName);
+      const cardType = this.project.resource<CardType>(cardTypeName);
       if (cardType === undefined) {
         throw new Error(`Card type '${cardTypeName}' does not exist`);
       }
-      if (parentCard && !this.hasCard(parentCard.key)) {
+      if (parentCard && !this.hasTemplateCard(parentCard.key)) {
         throw new Error(
           `Card '${parentCard.key}' does not exist in template '${this.containerName}'`,
         );
@@ -401,8 +414,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 +426,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 +441,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 +450,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 +489,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 +501,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,9 +513,10 @@ 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);
   }
 
   /**
@@ -540,8 +524,8 @@ export class Template extends CardContainer {
    * @param cardKey Card key to find from template.
    * @return 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);
   }
 
   /**
@@ -553,11 +537,25 @@ export class Template extends CardContainer {
   }
 
   /**
-   * 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 +566,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 +573,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

@@ -43,7 +43,7 @@ export interface CalculationContent {
 
 // Content interface for Graph Model resources
 export interface GraphModelContent {
-  model?: string;
+  model: string;
 }
 
 // Content interface for Graph View resources
@@ -58,6 +58,12 @@ export interface ReportContent {
   schema?: Schema;
 }
 
+export type FolderResourceContent =
+  | CalculationContent
+  | GraphModelContent
+  | GraphViewContent
+  | ReportContent;
+
 /**
  * Get filename with property name
  * @param propertyName Property name.

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

package/src/interfaces/resource-interfaces.ts

@@ -46,12 +46,6 @@ export interface CardType extends ResourceBaseMetadata {
   optionallyVisibleFields: string[];
 }
 
-// Base content update key interface
-export interface ContentUpdateKey {
-  key: 'content';
-  subKey: string; // Resource-specific types should narrow this
-}
-
 // Custom field
 // todo: merge with FieldType.
 export interface CustomField {
@@ -95,11 +89,6 @@ export interface GraphModel extends GraphModelMetadata {
   content: GraphModelContent;
 }
 export type GraphModelContentPropertyName = 'model';
-export interface GraphModelContentUpdateKey {
-  key: 'content';
-  subKey: GraphModelContentPropertyName;
-}
-export type GraphModelUpdateKey = string | GraphModelContentUpdateKey;
 
 // Graph view content.
 export interface GraphViewMetadata extends ResourceBaseMetadata {
@@ -109,11 +98,6 @@ export type GraphViewContentPropertyName = 'viewTemplate';
 export interface GraphView extends GraphViewMetadata {
   content: GraphViewContent;
 }
-export interface GraphViewContentUpdateKey {
-  key: 'content';
-  subKey: GraphViewContentPropertyName;
-}
-export type GraphViewUpdateKey = string | GraphViewContentUpdateKey;
 
 // Link content.
 export interface Link {
@@ -132,7 +116,7 @@ export interface LinkType extends ResourceBaseMetadata {
 }
 
 // Report resource.
-export interface Report extends ResourceBaseMetadata {
+export interface Report extends ReportMetadata {
   content: ReportContent;
 }
 
@@ -141,11 +125,6 @@ export type ReportContentPropertyName =
   | 'contentTemplate'
   | 'queryTemplate'
   | 'schema';
-export interface ReportContentUpdateKey {
-  key: 'content';
-  subKey: ReportContentPropertyName;
-}
-export type ReportUpdateKey = string | ReportContentUpdateKey;
 
 // Metadata for report
 export interface ReportMetadata extends ResourceBaseMetadata {
@@ -182,9 +161,18 @@ export interface TemplateConfiguration extends TemplateMetadata {
 export interface TemplateMetadata extends ResourceBaseMetadata {
   category?: string;
 }
+type ContentUpdateKey = { key: 'content'; subKey: string };
+type PropertyUpdateKey<K extends string = string> = {
+  key: Exclude<K, 'content'>;
+};
 
-// Generic update key
-export type UpdateKey = string | ContentUpdateKey;
+export type UpdateKey<K extends string = string> =
+  | ContentUpdateKey
+  | PropertyUpdateKey<K>;
+
+export function isContentKey(key: UpdateKey): key is ContentUpdateKey {
+  return key.key === 'content';
+}
 
 // Workflow's json file content.
 export interface Workflow extends ResourceBaseMetadata {

package/src/macros/createCards/index.ts

@@ -12,23 +12,12 @@
 
 import { createHtmlPlaceholder, validateMacroContent } from '../index.js';
 
+import type { CreateCardsOptions } from './types.js';
 import type { MacroGenerationContext } from '../../interfaces/macros.js';
 import macroMetadata from './metadata.js';
 import BaseMacro from '../base-macro.js';
 import type TaskQueue from '../task-queue.js';
 
-export interface CreateCardsOptions {
-  buttonLabel: string;
-  template: string;
-  cardKey?: string;
-  link?: {
-    linkType: string;
-    direction: string;
-    cardKey: string;
-  };
-  [key: string]: string | undefined | { [key: string]: string | undefined };
-}
-
 class CreateCardsMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);

package/src/macros/createCards/types.ts

@@ -0,0 +1,46 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  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/>.
+*/
+
+export interface CreateCardsOptions {
+  /**
+   * Label of the button
+   */
+  buttonLabel: string;
+  /**
+   * Template to create cards from
+   */
+  template: string;
+  /**
+   * Allows forcing card creation under a certain card
+   */
+  cardKey?: string;
+
+  /**
+   * Allows creating a link at the same time
+   */
+  link?: {
+    /**
+     * Type of the link to create
+     */
+    linkType: string;
+    /**
+     * Direction of the link to create
+     */
+    direction: string;
+    /**
+     * Card key of target card of the link
+     */
+    cardKey: string;
+  };
+}

package/src/macros/graph/index.ts

@@ -12,6 +12,7 @@
 */
 
 import BaseMacro from '../base-macro.js';
+import type { GraphOptions } from './types.js';
 import { createImage, validateMacroContent } from '../index.js';
 import Handlebars from 'handlebars';
 import type { MacroGenerationContext } from '../../interfaces/macros.js';
@@ -25,12 +26,7 @@ import { ClingoError } from '@cyberismo/node-clingo';
 import { resourceFilePath } from '../../utils/resource-utils.js';
 import { resourceName } from '../../utils/resource-utils.js';
 
-export interface GraphOptions {
-  model: string;
-  view: string;
-}
-
-class ReportMacro extends BaseMacro {
+class GraphMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
     super(macroMetadata, tasksQueue);
   }
@@ -129,4 +125,4 @@ class ReportMacro extends BaseMacro {
   }
 }
 
-export default ReportMacro;
+export default GraphMacro;