@cyberismo/data-handler 0.0.13 → 0.0.15

package/src/macros/xref/index.ts

@@ -17,10 +17,7 @@ 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 XrefMacroOptions {
-  cardKey: string;
-}
+import type { XrefMacroOptions } from './types.js';
 
 export default class XrefMacro extends BaseMacro {
   constructor(tasksQueue: TaskQueue) {
@@ -36,7 +33,7 @@ export default class XrefMacro extends BaseMacro {
     input: unknown,
   ): Promise<string> => {
     const options = this.validate(input);
-    const card = await this.getCard(options.cardKey, context);
+    const card = this.getCard(options.cardKey, context);
 
     if (!card || !card.metadata) {
       throw new Error(`Card key ${options.cardKey} not found`);
@@ -48,23 +45,12 @@ export default class XrefMacro extends BaseMacro {
 
   handleInject = async (context: MacroGenerationContext, input: unknown) => {
     const options = this.validate(input);
-    const card = await this.getCard(options.cardKey, context);
-
-    if (!card || !card.metadata) {
-      throw new Error(`Card key ${options.cardKey} not found`);
-    }
-
-    return `xref:${options.cardKey}.adoc[${card.metadata.title}]`;
+    const card = this.getCard(options.cardKey, context);
+    return `xref:${options.cardKey}.adoc[${card?.metadata?.title}]`;
   };
 
-  private async getCard(cardKey: string, context: MacroGenerationContext) {
-    const card = await context.project.cardDetailsById(cardKey, {
-      metadata: true,
-    });
-    if (!card || !card.metadata) {
-      throw new Error(`Card key ${cardKey} not found`);
-    }
-    return card;
+  private getCard(cardKey: string, context: MacroGenerationContext) {
+    return context.project.findCard(cardKey);
   }
 
   private validate(input: unknown): XrefMacroOptions {

package/src/macros/xref/types.ts

@@ -0,0 +1,20 @@
+/**
+  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 XrefMacroOptions {
+  /**
+   * Card of the card being referenced
+   */
+  cardKey: string;
+}

package/src/module-manager.ts

@@ -309,10 +309,10 @@ export class ModuleManager {
 
   // Collect modules that could be removed from .cards/modules when
   // 'moduleName' is removed.
-  private async orphanedModules(
+  private orphanedModules(
     dependencies: DependencyGraph,
     moduleName: string,
-  ): Promise<string[]> {
+  ): string[] {
     const projectModules = this.project.configuration.modules;
     const removableTransientModules: string[] = [];
     if (dependencies.has(moduleName)) {
@@ -558,6 +558,7 @@ export class ModuleManager {
       );
     }
     const sourceProject = new Project(source);
+    await sourceProject.populateCaches();
     const modulePrefix = sourceProject.projectPrefix;
     const destinationPath = join(
       this.project.paths.modulesFolder,
@@ -625,7 +626,7 @@ export class ModuleManager {
     // but modules under .cards/modules must be checked not to be used by
     // other modules.
     if (this.canBeRemoved(dependencies, moduleName)) {
-      const orphans = await this.orphanedModules(dependencies, moduleName);
+      const orphans = this.orphanedModules(dependencies, moduleName);
       await deleteDir(module.path);
       for (const moduleToDelete of orphans) {
         const modulePath = join(
@@ -634,9 +635,8 @@ export class ModuleManager {
         );
         await deleteDir(modulePath);
       }
-      await this.project.collectModuleResources();
     }
-    await this.project.configuration.removeModule(moduleName);
+    await this.project.removeModule(moduleName);
   }
 
   /**

package/src/project-settings.ts

@@ -61,7 +61,7 @@ export class ProjectConfiguration implements ProjectSettings {
 
   // Sets configuration values from file.
   private readSettings() {
-    const settings = readJsonFileSync(this.settingPath) as ProjectConfiguration;
+    const settings = readJsonFileSync(this.settingPath);
     if (!settings) {
       throw new Error(`File at '${this.settingPath}' is not a valid JSON file`);
     }

package/src/resources/calculation-resource.ts

@@ -0,0 +1,101 @@
+/**
+  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/>.
+*/
+
+import { join } from 'node:path';
+
+import {
+  DefaultContent,
+  FolderResource,
+  resourceNameToString,
+  sortCards,
+} from './folder-resource.js';
+import { writeFileSafe } from '../utils/file-utils.js';
+
+import { type CalculationMetadata } from '../interfaces/resource-interfaces.js';
+import type { CalculationContent } from '../interfaces/folder-content-interfaces.js';
+import type { Card, Project, ResourceName } from './file-resource.js';
+
+/**
+ * Calculation resource class.
+ */
+export class CalculationResource extends FolderResource<
+  CalculationMetadata,
+  CalculationContent
+> {
+  private calculationsFile = 'calculation.lp';
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'calculations');
+
+    this.contentSchemaId = 'calculationSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+  }
+
+  // When resource name changes
+  protected async onNameChange(existingName: string) {
+    await super.updateCalculations(existingName, this.content.name);
+    await this.write();
+  }
+
+  /**
+   * Creates a new calculation object and file.
+   * @param newContent Content for the calculation.
+   */
+  public async create(newContent?: CalculationMetadata) {
+    if (!newContent) {
+      newContent = DefaultContent.calculation(
+        resourceNameToString(this.resourceName),
+      );
+    } else {
+      await this.validate(newContent);
+    }
+    await super.create(newContent);
+
+    const calculationsFile = join(this.internalFolder, this.calculationsFile);
+    await writeFileSafe(
+      calculationsFile,
+      `% add your calculations here for '${this.resourceName.identifier}'`,
+      {
+        flag: 'wx',
+      },
+    );
+  }
+  /**
+   * Renames resource metadata file and renames memory resident object 'name'.
+   * @param newName New name for the resource.
+   */
+  public async rename(newName: ResourceName) {
+    const existingName = this.content.name;
+    await super.rename(newName);
+    return this.onNameChange(existingName);
+  }
+
+  /**
+   * List where calculation resource is used in cards, or other calculation resources.
+   * Always returns card key references first, then calculation references.
+   *
+   * @param cards Optional. Check these cards for usage of this resource. If undefined, will check all cards.
+   * @returns array of card keys and calculation filenames that refer this resource.
+   */
+  public async usage(cards?: Card[]): Promise<string[]> {
+    const allCards = cards || (await super.cards());
+
+    const [cardContentReferences, calculations] = await Promise.all([
+      super.usage(allCards),
+      super.calculations(),
+    ]);
+
+    const cardReferences = cardContentReferences.sort(sortCards);
+    return [...new Set([...cardReferences, ...calculations])];
+  }
+}

package/src/resources/card-type-resource.ts

@@ -16,6 +16,7 @@ import type {
   CardType,
   CustomField,
   LinkType,
+  UpdateKey,
   Workflow,
 } from '../interfaces/resource-interfaces.js';
 import { FieldTypeResource } from './field-type-resource.js';
@@ -40,19 +41,18 @@ import { Validate } from '../commands/index.js';
 /**
  * Card type resource class.
  */
-export class CardTypeResource extends FileResource {
+export class CardTypeResource extends FileResource<CardType> {
   constructor(project: Project, name: ResourceName) {
     super(project, name, 'cardTypes');
 
     this.contentSchemaId = 'cardTypeSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
 
-    this.initialize();
     this.setContainerValues();
   }
 
   // Returns cards that have this card type.
-  private async cardsWithCardType(cards: Card[]): Promise<string[]> {
+  private cardsWithCardType(cards: Card[]): string[] {
     const resourceName = resourceNameToString(this.resourceName);
     return cards
       .filter((card) => card.metadata?.cardType === resourceName)
@@ -72,13 +72,7 @@ export class CardTypeResource extends FileResource {
     if (op && op.name === 'rank') return;
 
     // Collect both project cards and template cards.
-    const cards = await this.collectCards(
-      {
-        metadata: true,
-        content: true,
-      },
-      this.content.name,
-    );
+    const cards = await this.collectCards(this.content.name);
 
     if (op && op.name === 'change') {
       const from = (op as ChangeOperation<string>).target;
@@ -113,7 +107,7 @@ export class CardTypeResource extends FileResource {
 
   // When resource name changes.
   private async handleNameChange(existingName: string) {
-    const current = this.content as CardType;
+    const current = this.content;
     const prefixes = await this.project.projectPrefixes();
     if (current.customFields) {
       current.customFields.map(
@@ -160,20 +154,14 @@ export class CardTypeResource extends FileResource {
     op: ChangeOperation<Type>,
   ) {
     await this.verifyStateMapping(stateMapping, op);
-    const cards = await this.collectCards(
-      {
-        metadata: true,
-        content: true,
-      },
-      this.content.name,
-    );
+    const cards = await this.collectCards(this.content.name);
 
     const unmappedStates: string[] = [];
 
     // Update each card's workflowState if it has a mapping
     const updatePromises = cards.map(async (card) => {
       if (card.metadata && card.metadata.workflowState) {
-        const currentState = card.metadata.workflowState as string;
+        const currentState = card.metadata.workflowState;
         const newState = stateMapping[currentState];
 
         if (newState && newState !== currentState) {
@@ -198,8 +186,10 @@ export class CardTypeResource extends FileResource {
   }
 
   // Checks if field type exists in this card type.
-  private async hasFieldType(field: Partial<CustomField>): Promise<boolean> {
-    return this.data.customFields.some((item) => item.name === field.name);
+  private hasFieldType(field: Partial<CustomField>): boolean {
+    return (
+      this.data?.customFields.some((item) => item.name === field.name) || false
+    );
   }
 
   // Remove value from array.
@@ -251,7 +241,7 @@ export class CardTypeResource extends FileResource {
 
   // Sets content container values to be either '[]' or with proper values.
   private setContainerValues() {
-    const content = this.content as CardType;
+    const content = this.content;
     if (content.customFields) {
       for (const item of content.customFields) {
         // Set "isCalculated" if it is missing; default = false
@@ -311,7 +301,7 @@ export class CardTypeResource extends FileResource {
             target: oldName,
             to: this.content.name,
           } as ChangeOperation<string>;
-          updates.push(object.update(field, op));
+          updates.push(object.update({ key: field }, op));
         }
       }
 
@@ -423,7 +413,7 @@ export class CardTypeResource extends FileResource {
         `Cannot create cardType without providing workflow for it`,
       );
     }
-    const validWorkflowName = await Validate.getInstance().validResourceName(
+    const validWorkflowName = Validate.getInstance().validResourceName(
       'workflows',
       resourceNameToString(resourceName(workflowName)),
       await this.project.projectPrefixes(),
@@ -441,20 +431,6 @@ export class CardTypeResource extends FileResource {
     return super.create(content);
   }
 
-  /**
-   * Returns content data.
-   */
-  public get data(): CardType {
-    return super.data as CardType;
-  }
-
-  /**
-   * Deletes file(s) from disk and clears out the memory resident object.
-   */
-  public async delete() {
-    return super.delete();
-  }
-
   /**
    * Renames resource metadata file and renames memory resident object 'name'.
    * @param newName New name for the resource.
@@ -465,26 +441,22 @@ export class CardTypeResource extends FileResource {
     return this.handleNameChange(existingName);
   }
 
-  /**
-   * Shows metadata of the resource.
-   * @returns card type metadata.
-   */
-  public async show(): Promise<CardType> {
-    return super.show() as Promise<CardType>;
-  }
-
   /**
    * Updates card type resource.
-   * @param key Key to modify
+   * @param updateKey Key to modify
    * @param op Operation to perform on 'key'
    */
-  public async update<Type>(key: string, op: Operation<Type>) {
+  public async update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    const { key } = updateKey;
     const nameChange = key === 'name';
     const customFieldsChange = key === 'customFields';
     const existingName = this.content.name;
-    await super.update(key, op);
+    await super.update(updateKey, op);
 
-    const content = structuredClone(this.content) as CardType;
+    const content = structuredClone(this.content);
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
     } else if (key === 'alwaysVisibleFields') {
@@ -525,7 +497,7 @@ export class CardTypeResource extends FileResource {
     } else {
       throw new Error(`Unknown property '${key}' for CardType`);
     }
-    await super.postUpdate(content, key, op);
+    await super.postUpdate(content, updateKey, op);
 
     // Renaming this card type causes that references to its name must be updated.
     if (nameChange) {
@@ -544,7 +516,7 @@ export class CardTypeResource extends FileResource {
    * @returns array of card keys, resource names and calculation filenames that refer this resource.
    */
   public async usage(cards?: Card[]): Promise<string[]> {
-    const allCards = cards ?? (await super.cards());
+    const allCards = cards ?? super.cards();
     const [
       cardsWithCardType,
       cardContentReferences,
@@ -566,11 +538,4 @@ export class CardTypeResource extends FileResource {
       ...new Set([...cardReferences, ...relevantLinkTypes, ...calculations]),
     ];
   }
-
-  /**
-   * Validates the resource. If object is invalid, throws.
-   */
-  public async validate(content?: object) {
-    return super.validate(content);
-  }
 }

package/src/resources/create-defaults.ts

@@ -1,18 +1,20 @@
 /**
   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
+  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 type { Card } from '../interfaces/project-interfaces.js';
 import type {
+  CalculationMetadata,
   CardType,
   DataType,
   FieldType,
@@ -70,6 +72,20 @@ export abstract class DefaultContent {
     );
   }
 
+  /**
+   * Default content for calculation.
+   * @param calculationName calculation name
+   * @returns Default content for calculation.
+   */
+  static calculation(calculationName: string): CalculationMetadata {
+    return {
+      name: calculationName,
+      displayName: '',
+      description: undefined,
+      calculation: 'calculation.lp',
+    };
+  }
+
   /**
    * Default content for card type.
    * @param cardTypeName card type name

package/src/resources/field-type-resource.ts

@@ -33,6 +33,7 @@ import type {
   DataType,
   EnumDefinition,
   FieldType,
+  UpdateKey,
 } from '../interfaces/resource-interfaces.js';
 import { CardTypeResource } from './card-type-resource.js';
 import {
@@ -48,7 +49,7 @@ const SHORT_TEXT_MAX_LENGTH = 80;
 /**
  * Field type resource class.
  */
-export class FieldTypeResource extends FileResource {
+export class FieldTypeResource extends FileResource<FieldType> {
   // Initialize data type change helpers (fromType, toType) to some values.
   // The actual types are set, if this Field Type's dataType is changed.
   private fromType: DataType = 'integer';
@@ -59,8 +60,6 @@ export class FieldTypeResource extends FileResource {
 
     this.contentSchemaId = 'fieldTypeSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
-
-    this.initialize();
   }
 
   // Cards from given array that include this field type.
@@ -130,7 +129,7 @@ export class FieldTypeResource extends FileResource {
     function affectedCard(card: Card): boolean {
       if (!card.metadata) return false;
       return cardTypesThatUseThisFieldType.some(
-        (item) => item === card.metadata!.cardType,
+        (item) => item === card.metadata?.cardType,
       );
     }
 
@@ -139,12 +138,11 @@ export class FieldTypeResource extends FileResource {
     cardTypesThatUseThisFieldType.push(...cardTypes);
 
     // Then collect cards (both project and local template) that use those card types.
-    const projectCards = (
-      await this.project.cards(this.project.paths.cardRootFolder, {
-        metadata: true,
-      })
-    ).filter((card) => affectedCard(card));
-    const templateCards = (await this.project.allTemplateCards())
+    const projectCards = this.project
+      .cards(this.project.paths.cardRootFolder)
+      .filter((card) => affectedCard(card));
+    const templateCards = this.project
+      .allTemplateCards()
       .filter((card) => !card.path.includes('modules'))
       .filter((card) => affectedCard(card));
     const allCards = [...projectCards, ...templateCards];
@@ -213,9 +211,7 @@ export class FieldTypeResource extends FileResource {
     const removedValue = (op.target as EnumDefinition).enumValue;
     const cardTypes = await this.relevantCardTypes(ResourcesFrom.localOnly);
     const allCards = await Promise.all(
-      cardTypes.map((cardType) =>
-        this.collectCards({ metadata: true }, cardType),
-      ),
+      cardTypes.map((cardType) => this.collectCards(cardType)),
     );
     const cardsToUpdate = allCards
       .flat()
@@ -290,13 +286,13 @@ export class FieldTypeResource extends FileResource {
         this.project,
         resourceName(cardType.name),
       );
-      const data = object.data as CardType;
+      const data = object.data;
       if (data) {
         const found = data.customFields
           ? data.customFields.find((item) => item.name === oldName)
           : undefined;
         if (found) {
-          await object.update('customFields', op);
+          await object.update({ key: 'customFields' }, op);
         }
       }
     }
@@ -322,20 +318,6 @@ export class FieldTypeResource extends FileResource {
     return super.create(content);
   }
 
-  /**
-   * Returns content data.
-   */
-  public get data(): FieldType {
-    return super.data as FieldType;
-  }
-
-  /**
-   * Deletes file(s) from disk and clears out the memory resident object.
-   */
-  public async delete() {
-    return super.delete();
-  }
-
   /**
    * Returns all possible field types.
    * @returns all possible field types.
@@ -407,33 +389,29 @@ export class FieldTypeResource extends FileResource {
     return this.handleNameChange(existingName);
   }
 
-  /**
-   * Shows metadata of the resource.
-   * @returns field type metadata.
-   */
-  public async show(): Promise<FieldType> {
-    return super.show() as Promise<FieldType>;
-  }
-
   /**
    * Updates field type resource.
-   * @param key Key to modify
+   * @param updateKey Key to modify
    * @param op Operation to perform on 'key'
    * @throws
    *  - when called with unknown data type
    *  - when called with data type conversion that cannot be done
    *  - when called with unknown property to update
    */
-  public async update<Type>(key: string, op: Operation<Type>) {
+  public async update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    const { key } = updateKey;
     const nameChange = key === 'name';
     const typeChange = key === 'dataType';
     const enumChange = key === 'enumValues';
     const existingName = this.content.name;
-    const existingType = (this.content as FieldType).dataType;
+    const existingType = this.content.dataType;
 
-    await super.update(key, op);
+    await super.update(updateKey, op);
 
-    const content = structuredClone(this.content) as FieldType;
+    const content = structuredClone(this.content);
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
     } else if (key === 'dataType') {
@@ -473,7 +451,7 @@ export class FieldTypeResource extends FileResource {
       throw new Error(`Unknown property '${key}' for FieldType`);
     }
 
-    await super.postUpdate(content, key, op);
+    await super.postUpdate(content, updateKey, op);
 
     if (nameChange) {
       // Renaming this field type causes that references to its name must be updated.
@@ -494,7 +472,7 @@ export class FieldTypeResource extends FileResource {
    * @returns array of card keys, resource names and calculation filenames that refer this resource.
    */
   public async usage(cards?: Card[]): Promise<string[]> {
-    const allCards = cards ?? (await super.cards());
+    const allCards = cards ?? super.cards();
 
     const [cardContentReferences, relevantLinkTypes, calculations] =
       await Promise.all([
@@ -513,11 +491,4 @@ export class FieldTypeResource extends FileResource {
       ...new Set([...cardReferences, ...relevantLinkTypes, ...calculations]),
     ];
   }
-
-  /**
-   * Validates the resource. If object is invalid, throws.
-   */
-  public async validate(content?: object) {
-    return super.validate(content);
-  }
 }