@cyberismo/data-handler 0.0.13 → 0.0.14

package/src/containers/project.ts

@@ -53,6 +53,7 @@ import {
 import type { Template } from './template.js';
 import { Validate } from '../commands/validate.js';
 
+import { CalculationResource } from '../resources/calculation-resource.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';
@@ -977,7 +978,9 @@ export class Project extends CardContainer {
    * @returns Created resource.
    */
   public static resourceObject(project: Project, name: ResourceName) {
-    if (name.type === 'cardTypes') {
+    if (name.type === 'calculations') {
+      return new CalculationResource(project, name);
+    } else if (name.type === 'cardTypes') {
       return new CardTypeResource(project, name);
     } else if (name.type === 'fieldTypes') {
       return new FieldTypeResource(project, name);

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

@@ -15,22 +15,32 @@ 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',
-  'query.lp.hbs': 'queryTemplate',
-  'parameterSchema.json': 'schema',
   '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',
-  model: 'model.lp',
   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;
@@ -64,6 +74,8 @@ export function filename(propertyName: string): string | undefined {
  * @param filename Filename.
  * @returns property name that matches filename
  */
-export function propertyName(filename: string): string | undefined {
+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

@@ -12,6 +12,7 @@
 */
 
 import type {
+  CalculationContent,
   GraphModelContent,
   GraphViewContent,
   ReportContent,
@@ -27,6 +28,15 @@ import type {
 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 {

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/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/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`);

package/src/resources/folder-resource.ts

@@ -216,7 +216,7 @@ export class FolderResource extends FileResource {
    * Updates content files from a content object.
    * @param contentFiles Object with file names as keys and file contents as values.
    */
-  public async updateContentFiles(contentFiles: Record<string, string>) {
+  protected async updateContentFiles(contentFiles: Record<string, string>) {
     for (const [fileName, fileContent] of Object.entries(contentFiles)) {
       await this.updateFile(fileName, fileContent);
     }
@@ -227,7 +227,7 @@ export class FolderResource extends FileResource {
    * @param fileName The name of the file to update.
    * @param changedContent The new content for the file.
    */
-  public async updateFile(fileName: string, changedContent: string) {
+  protected async updateFile(fileName: string, changedContent: string) {
     const filePath = join(this.internalFolder, fileName);
 
     // Do not allow updating file in other directories

package/src/resources/resource-object.ts

@@ -16,6 +16,8 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 
+import { hasCode } from '../utils/error-utils.js';
+
 import { ArrayHandler } from './array-handler.js';
 import type {
   Card,
@@ -222,19 +224,29 @@ export class ResourceObject extends AbstractResource {
           );
         }
 
-        const filename = join(
-          calculation.path,
-          basename(calculation.name) + '.lp',
-        );
+        const base = basename(calculation.name);
+        const fileNameWithExtension = base.endsWith('.lp')
+          ? base
+          : base + '.lp';
+        const filename = join(calculation.path, fileNameWithExtension);
 
         try {
           const content = await readFile(filename, 'utf-8');
           const updatedContent = content.replaceAll(from, to);
           await writeFile(filename, updatedContent);
         } catch (error) {
-          throw new Error(
-            `Failed to process file ${filename}: ${(error as Error).message}`,
-          );
+          if (hasCode(error) && error.code === 'ENOENT') {
+            // Skip files that don't exist (they may have been renamed or deleted)
+            this.getLogger(this.getType).warn(
+              `Skipping non-existent file: ${filename}`,
+            );
+            return;
+          }
+          if (error instanceof Error) {
+            throw new Error(
+              `Failed to process file while updating calculation ${filename}: ${error.message}`,
+            );
+          }
         }
       }),
     );

package/src/utils/constants.ts

@@ -29,6 +29,7 @@ export const VALID_FOLDER_RESOURCE_FILES = [
   'parameterSchema.json',
   'view.lp.hbs',
   'model.lp',
+  'calculation.lp',
 ];
 
 /**

package/src/utils/error-utils.ts

@@ -0,0 +1,62 @@
+/**
+  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/>.
+*/
+
+/**
+ * Returns error message string from an Error object.
+ * @param error Error object
+ * @returns Error message.
+ */
+export function errorFunction(error: unknown): string {
+  if (error instanceof Error) {
+    const err: Error = error;
+    return errorMessage(`${err.message}`);
+  } else if (typeof error === 'string') {
+    return errorMessage(`${error}`);
+  } else {
+    return `errorFunction called without an error object. Actual object is ${JSON.stringify(error)}`;
+  }
+}
+
+/**
+ * Same as 'errorFunction' but can do automatic replacement of the error message string.
+ * @param message Error message
+ * @param toReplace replacement substring
+ * @param replaceWith string that 'toReplace' is replaced with.
+ * @returns Modified error message.
+ */
+export function errorMessage(
+  message: string,
+  toReplace?: string,
+  replaceWith?: string,
+): string {
+  let errorMessage = message;
+  if (toReplace && replaceWith) {
+    errorMessage = message.replace(toReplace, replaceWith);
+  }
+  return `${errorMessage}`;
+}
+
+/**
+ * Type guard to check if an error object has a code property.
+ * @param error The error object to check
+ * @returns true if the error has a code property
+ */
+export function hasCode(error: unknown): error is Error & { code: string } {
+  return (
+    error instanceof Error &&
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    typeof error.code === 'string'
+  );
+}

package/src/utils/log-utils.ts

@@ -36,71 +36,3 @@ export function getChildLogger(
 ): Logger {
   return _logger.child(context, options);
 }
-/**
- * Returns error message string from an Error object.
- * @param error Error object
- * @returns Error message.
- */
-export function errorFunction(error: unknown): string {
-  if (error instanceof Error) {
-    const err: Error = error;
-    return errorMessage(`${err.message}`);
-  } else if (typeof error === 'string') {
-    return errorMessage(`${error}`);
-  } else {
-    return `${logError.name} called without an error object. Actual object is ${JSON.stringify(error)}`;
-  }
-}
-
-/**
- * Same as 'errorFunction' but can do automatic replacement fof the error message string.
- * @param message Error message
- * @param toReplace replacement substring
- * @param replaceWith string that 'toReplace' is replaced with.
- * @returns Modified error message.
- */
-export function errorMessage(
-  message: string,
-  toReplace?: string,
-  replaceWith?: string,
-): string {
-  let errorMessage = message;
-  if (toReplace && replaceWith) {
-    errorMessage = message.replace(toReplace, replaceWith);
-  }
-  return `${errorMessage}`;
-}
-
-/**
- * Logs error from Error object.
- * @param error potentially an Error object. When exceptions are raised, they are typically Error objects.
- */
-export function logError(error: unknown) {
-  if (error instanceof Error) {
-    const err: Error = error;
-    logErrorMessage(`${err.message}`);
-  } else {
-    console.error(
-      `${logError.name} called without an error object. Actual object is ${JSON.stringify(error)}`,
-    );
-  }
-}
-
-/**
- * Log error message in RED. Certain parts of messages can be replaced.
- * This is useful, if including a message from external sources, and want to reduce the verbosity of the message.
- * @param message Error message to log.
- * @param toReplace String to look for.
- * @param replaceWith Replace 'toReplace' with this. Only replaces first instance of 'toReplace'.
- */
-export function logErrorMessage(
-  message: string,
-  toReplace?: string,
-  replaceWith?: string,
-) {
-  let errorMessage = message;
-  if (toReplace && replaceWith) {
-    errorMessage = message.replace(toReplace, replaceWith);
-  }
-  console.error(`${errorMessage}`);
-}

package/src/utils/user-preferences.ts

@@ -12,6 +12,7 @@
 import { dirname } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 
+import { hasCode } from './error-utils.js';
 import { formatJson } from './json.js';
 import { getChildLogger } from '../utils/log-utils.js';
 
@@ -111,16 +112,19 @@ export class UserPreferences {
         flag: 'wx',
       });
     } catch (error) {
-      if (error instanceof Error) {
-        const err = error as NodeJS.ErrnoException;
+      if (hasCode(error)) {
         // If file already exists (EEXIST), that's fine - we'll use the existing file
-        if (err?.code !== 'EEXIST') {
+        if (error.code !== 'EEXIST') {
           throw new Error(
             `Error creating preferences file '${this.prefsFilePath}': ${error}`,
           );
         } else {
           this.logger.warn('Preferences file already exists');
         }
+      } else {
+        throw new Error(
+          `Error creating preferences file '${this.prefsFilePath}': ${error}`,
+        );
       }
     }
   }