@cyberismo/data-handler 0.0.12 → 0.0.14

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

@@ -0,0 +1,81 @@
+/**
+  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 type { Schema } from 'jsonschema';
+
+// All file mappings for lookup (filename -> property name)
+export const ALL_FILE_MAPPINGS = {
+  'calculation.lp': 'calculation',
+  'index.adoc.hbs': 'contentTemplate',
+  'model.lp': 'model',
+  'parameterSchema.json': 'schema',
+  'query.lp.hbs': 'queryTemplate',
+  'view.lp.hbs': 'viewTemplate',
+} as const;
+
+// Reverse mappings from property names to filenames
+export const REVERSE_FILE_MAPPINGS = {
+  calculation: 'calculation.lp',
+  contentTemplate: 'index.adoc.hbs',
+  model: 'model.lp',
+  queryTemplate: 'query.lp.hbs',
+  schema: 'parameterSchema.json',
+  viewTemplate: 'view.lp.hbs',
+} as const;
+
+// Union type of all valid content property names
+export type ContentPropertyName = keyof typeof REVERSE_FILE_MAPPINGS;
+
+// Content interface for Calculation resources
+export interface CalculationContent {
+  calculation: string;
+}
+
+// Content interface for Graph Model resources
+export interface GraphModelContent {
+  model?: string;
+}
+
+// Content interface for Graph View resources
+export interface GraphViewContent {
+  viewTemplate?: string;
+}
+
+// Content interface for Report resources
+export interface ReportContent {
+  contentTemplate: string;
+  queryTemplate: string;
+  schema?: Schema;
+}
+
+/**
+ * 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
+  ];
+}
+
+/**
+ * Get property name for a filename
+ * @param filename Filename.
+ * @returns property name that matches filename
+ */
+export function propertyName(
+  filename: string,
+): ContentPropertyName | undefined {
+  return ALL_FILE_MAPPINGS[filename as keyof typeof ALL_FILE_MAPPINGS];
+}

package/src/interfaces/project-interfaces.ts

@@ -1,13 +1,15 @@
 /**
-    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/>.
+  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 type { Link, TemplateConfiguration } from './resource-interfaces.js';
@@ -205,6 +207,7 @@ export interface ModuleSettingOptions {
 // Resources that are possible to remove.
 export type RemovableResourceTypes =
   | 'attachment'
+  | 'calculation'
   | 'card'
   | 'cardType'
   | 'fieldType'

package/src/interfaces/resource-interfaces.ts

@@ -11,7 +11,12 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import type { Schema } from 'jsonschema';
+import type {
+  CalculationContent,
+  GraphModelContent,
+  GraphViewContent,
+  ReportContent,
+} from './folder-content-interfaces.js';
 
 /**
  * Each resource represents a file (or a folder in some cases) with metadata stored
@@ -23,6 +28,15 @@ import type { Schema } from 'jsonschema';
 export interface CalculationMetadata extends ResourceBaseMetadata {
   calculation: string;
 }
+export interface Calculation extends CalculationMetadata {
+  content: CalculationContent;
+}
+export type CalculationContentPropertyName = 'calculation';
+export interface CalculationContentUpdateKey {
+  key: 'content';
+  subKey: CalculationContentPropertyName;
+}
+export type CalculationUpdateKey = string | CalculationContentUpdateKey;
 
 // Card type content.
 export interface CardType extends ResourceBaseMetadata {
@@ -32,6 +46,12 @@ 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 {
@@ -71,19 +91,29 @@ export interface FieldType extends ResourceBaseMetadata {
 export interface GraphModelMetadata extends ResourceBaseMetadata {
   category?: string;
 }
-
 export interface GraphModel extends GraphModelMetadata {
-  calculationFile: string;
+  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 {
   category?: string;
 }
-
+export type GraphViewContentPropertyName = 'viewTemplate';
 export interface GraphView extends GraphViewMetadata {
-  handleBarFile: string;
+  content: GraphViewContent;
+}
+export interface GraphViewContentUpdateKey {
+  key: 'content';
+  subKey: GraphViewContentPropertyName;
 }
+export type GraphViewUpdateKey = string | GraphViewContentUpdateKey;
 
 // Link content.
 export interface Link {
@@ -103,13 +133,20 @@ export interface LinkType extends ResourceBaseMetadata {
 
 // Report resource.
 export interface Report extends ResourceBaseMetadata {
-  name: string;
-  metadata: ReportMetadata;
-  contentTemplate: string;
-  queryTemplate: string;
-  schema?: Schema;
+  content: ReportContent;
 }
 
+// Resource-specific content names
+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 {
   category: string;
@@ -136,10 +173,9 @@ export type ResourceContent =
   | Workflow;
 
 // Template configuration details.
-export interface TemplateConfiguration extends ResourceBaseMetadata {
+export interface TemplateConfiguration extends TemplateMetadata {
   path: string;
   numberOfCards: number;
-  metadata: TemplateMetadata;
 }
 
 // Template configuration content details.
@@ -147,6 +183,9 @@ export interface TemplateMetadata extends ResourceBaseMetadata {
   category?: string;
 }
 
+// Generic update key
+export type UpdateKey = string | ContentUpdateKey;
+
 // Workflow's json file content.
 export interface Workflow extends ResourceBaseMetadata {
   states: WorkflowState[];

package/src/macros/report/index.ts

@@ -45,16 +45,16 @@ class ReportMacro extends BaseMacro {
 
     if (!report) throw new Error(`Report ${options.name} does not exist`);
 
-    if (report.schema) {
+    if (report.content.schema) {
       validateJson(options, {
-        schema: report.schema,
+        schema: report.content.schema,
       });
     }
     try {
       return await generateReportContent({
         calculate: context.project.calculationEngine,
-        contentTemplate: report.contentTemplate,
-        queryTemplate: report.queryTemplate,
+        contentTemplate: report.content.contentTemplate,
+        queryTemplate: report.content.queryTemplate,
         options: {
           cardKey: context.cardKey,
           ...options,

package/src/resources/calculation-resource.ts

@@ -0,0 +1,171 @@
+/**
+  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 {
+  Calculation,
+  CalculationMetadata,
+  CalculationUpdateKey,
+} from '../interfaces/resource-interfaces.js';
+import type { CalculationContent } from '../interfaces/folder-content-interfaces.js';
+import type {
+  Card,
+  Operation,
+  Project,
+  ResourceName,
+} from './file-resource.js';
+
+/**
+ * Calculation resource class.
+ */
+export class CalculationResource extends FolderResource {
+  private calculationsFile = 'calculation.lp';
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'calculations');
+
+    this.contentSchemaId = 'calculationSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+
+    this.initialize();
+  }
+
+  // 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',
+      },
+    );
+  }
+
+  /**
+   * Returns content data.
+   */
+  public get data(): CalculationMetadata {
+    return super.data as CalculationMetadata;
+  }
+
+  /**
+   * Deletes files from disk and clears out the memory resident object.
+   */
+  public async delete() {
+    await super.delete();
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * Shows metadata of the resource.
+   * @returns calculation metadata.
+   */
+  public async show(): Promise<Calculation> {
+    const baseData = (await super.show()) as CalculationMetadata;
+    const fileContents = await super.contentData();
+    const content: CalculationContent = {
+      calculation: fileContents.calculation as string,
+    };
+    return {
+      ...baseData,
+      content: content,
+    };
+  }
+
+  /**
+   * Updates calculation resource.
+   * @template Type The type of the operation being operated on for the given key.
+   * @param key Key to modify
+   * @param op Operation to perform on 'key'
+   * @example
+   * // Update the description
+   *    await calculation.update('description', { name: 'change', to: 'New description' });
+   *    await calculation.update({ key: 'content', subKey: 'calculation' }, { name: 'change', to: 'new content' });
+   */
+  public async update<Type>(key: CalculationUpdateKey, op: Operation<Type>) {
+    if (
+      typeof key === 'object' &&
+      key.key === 'content' &&
+      key.subKey === 'calculation'
+    ) {
+      const calculationContent = super.handleScalar(op) as string;
+      await this.updateFile(this.calculationsFile, calculationContent);
+      return;
+    }
+    await super.update(key, op);
+  }
+
+  /**
+   * 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])];
+  }
+
+  /**
+   * Validates the resource. If object is invalid, throws.
+   * @param content Content to validate
+   */
+  public async validate(content?: object) {
+    return super.validate(content);
+  }
+}

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

@@ -233,7 +233,10 @@ export class CardTypeResource extends FileResource {
   }
 
   // If value from 'customFields' is removed, remove it also from 'optionallyVisible' and 'alwaysVisible' arrays.
-  private removeValueFromOtherArrays<Type>(op: Operation<Type>) {
+  private removeValueFromOtherArrays<Type>(
+    op: Operation<Type>,
+    content: CardType,
+  ) {
     // Update target can be a string, or an object. Of object, fetch only 'name'
     // todo: fetching 'name' or using string as name could be function in resource base class.
     const target = (op as RemoveOperation<Type>).target as Type;
@@ -242,8 +245,8 @@ export class CardTypeResource extends FileResource {
       field = { name: target['name' as keyof Type] };
     }
     const fieldName = (field ? field.name : target) as string;
-    this.removeValue(this.data.alwaysVisibleFields, fieldName);
-    this.removeValue(this.data.optionallyVisibleFields, fieldName);
+    this.removeValue(content.alwaysVisibleFields, fieldName);
+    this.removeValue(content.optionallyVisibleFields, fieldName);
   }
 
   // Sets content container values to be either '[]' or with proper values.
@@ -481,7 +484,7 @@ export class CardTypeResource extends FileResource {
     const existingName = this.content.name;
     await super.update(key, op);
 
-    const content = this.content as CardType;
+    const content = structuredClone(this.content) as CardType;
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
     } else if (key === 'alwaysVisibleFields') {
@@ -513,12 +516,15 @@ export class CardTypeResource extends FileResource {
         content.customFields as Type[],
       ) as CustomField[];
       if (op.name === 'remove') {
-        this.removeValueFromOtherArrays(op);
+        this.removeValueFromOtherArrays(op, content);
       }
+    } else if (key === 'description') {
+      content.description = super.handleScalar(op) as string;
+    } else if (key === 'displayName') {
+      content.displayName = super.handleScalar(op) as string;
     } else {
       throw new Error(`Unknown property '${key}' for CardType`);
     }
-
     await super.postUpdate(content, key, op);
 
     // Renaming this card type causes that references to its name must be updated.

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

@@ -433,7 +433,7 @@ export class FieldTypeResource extends FileResource {
 
     await super.update(key, op);
 
-    const content = this.content as FieldType;
+    const content = structuredClone(this.content) as FieldType;
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
     } else if (key === 'dataType') {

package/src/resources/file-resource.ts

@@ -30,6 +30,7 @@ import {
 } from './resource-object.js';
 import { DefaultContent } from './create-defaults.js';
 import { deleteFile, pathExists } from '../utils/file-utils.js';
+import { hasCode } from '../utils/error-utils.js';
 import { Project, ResourcesFrom } from '../containers/project.js';
 import {
   readJsonFile,
@@ -242,6 +243,11 @@ export class FileResource extends ResourceObject {
           references.push(calculation.name);
         }
       } catch (error) {
+        // Skip files that don't exist (they may have been renamed or deleted)
+        if (hasCode(error) && error.code === 'ENOENT') {
+          this.logger.warn(`Skipping non-existent file: ${filename}`);
+          continue;
+        }
         throw new Error(
           `Failed to process file ${filename}: ${(error as Error).message}`,
         );
@@ -397,9 +403,9 @@ export class FileResource extends ResourceObject {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _op: Operation<Type>,
   ): Promise<void> {
-    const content = this.data;
-    if (!content) {
-      throw new Error(`Resource '${this.fileName}' does not exist`);
+    if (!this.data) {
+      const name = resourceNameToString(this.resourceName);
+      throw new Error(`Resource '${name}' does not exist in the project`);
     }
     if (this.moduleResource) {
       throw new Error(`Cannot update module resources`);