@cyberismo/data-handler 0.0.12 → 0.0.13

package/src/interfaces/resource-interfaces.ts

@@ -11,7 +11,11 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import type { Schema } from 'jsonschema';
+import type {
+  GraphModelContent,
+  GraphViewContent,
+  ReportContent,
+} from './folder-content-interfaces.js';
 
 /**
  * Each resource represents a file (or a folder in some cases) with metadata stored
@@ -32,6 +36,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 +81,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 +123,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 +163,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 +173,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/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/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/folder-resource.ts

@@ -1,35 +1,44 @@
 /**
   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 { basename, dirname, join, normalize } from 'node:path';
 import { mkdir, readdir, readFile, rename, rm } from 'node:fs/promises';
 
-import { writeFileSafe } from '../utils/file-utils.js';
-
+import type { Card, Operation, ResourceName } from './file-resource.js';
+import type {
+  ContentUpdateKey,
+  ResourceContent,
+  UpdateKey,
+} from '../interfaces/resource-interfaces.js';
 import type { ResourceFolderType } from '../interfaces/project-interfaces.js';
+import type { Schema } from 'jsonschema';
+
 import {
-  type Card,
   DefaultContent,
   FileResource,
-  type Operation,
   Project,
   resourceName,
-  type ResourceName,
   resourceNameToString,
   sortCards,
 } from './file-resource.js';
-import type { ResourceContent } from '../interfaces/resource-interfaces.js';
+import {
+  filename,
+  propertyName,
+} from '../interfaces/folder-content-interfaces.js';
+import { readJsonFile } from '../utils/json.js';
 import { VALID_FOLDER_RESOURCE_FILES } from '../utils/constants.js';
+import { writeFileSafe } from '../utils/file-utils.js';
 
 export {
   type Card,
@@ -48,10 +57,23 @@ export {
 export class FolderResource extends FileResource {
   protected internalFolder: string = '';
 
+  // Cache for content files to avoid repeated filesystem operations. Content is stored as string.
+  private contentFilesCache = new Map<string, string>();
+
   constructor(project: Project, name: ResourceName, type: ResourceFolderType) {
     super(project, name, type);
   }
 
+  // Clears the content files cache.
+  private clearContentCache() {
+    this.contentFilesCache.clear();
+  }
+
+  // Type guard to check if a key is a ContentUpdateKey
+  private isContentUpdateKey(key: UpdateKey): key is ContentUpdateKey {
+    return typeof key === 'object' && key.key === 'content' && 'subKey' in key;
+  }
+
   /**
    * Creates a new folder type object. Base class writes the object to disk automatically.
    * @param newContent Content for the type.
@@ -61,6 +83,25 @@ export class FolderResource extends FileResource {
     await mkdir(this.internalFolder, { recursive: true });
   }
 
+  /**
+   * Gets content of all files to properties.
+   * @returns object with property names as keys and file contents as values.
+   */
+  public async contentData(): Promise<Record<string, string | Schema>> {
+    const fileNames = await this.showFileNames();
+    const content: Record<string, string | Schema> = {};
+
+    for (const fileName of fileNames) {
+      const name = propertyName(fileName);
+      if (name) {
+        const JSONFile = name === 'schema';
+        content[name] = await this.showFile(fileName, JSONFile);
+      }
+    }
+
+    return content;
+  }
+
   /**
    * Returns content data.
    */
@@ -74,6 +115,7 @@ export class FolderResource extends FileResource {
   protected async delete() {
     await super.delete();
     await rm(this.internalFolder, { recursive: true, force: true });
+    this.clearContentCache();
   }
 
   // Get (resource folder) type name
@@ -81,11 +123,15 @@ export class FolderResource extends FileResource {
     return super.getType;
   }
 
+  // Get logger instance
   protected get logger() {
     return super.getLogger(this.getType);
   }
 
-  protected initialize(): void {
+  /**
+   * Initialize the resource item.
+   */
+  protected initialize() {
     super.initialize();
 
     this.internalFolder = join(
@@ -111,22 +157,69 @@ export class FolderResource extends FileResource {
   }
 
   /**
+   * TODO: to be made protected - no direct access to files
    * Shows the content of a file in the resource.
    * @param fileName Name of the file to show.
+   * @param json Content is JSON file.
    * @returns the content of the file.
    */
-  public async showFile(fileName: string): Promise<string> {
+  public async showFile(
+    fileName: string,
+    json: boolean = false,
+  ): Promise<string> {
+    // Always first check cache...
+    if (this.contentFilesCache.has(fileName)) {
+      const cached = this.contentFilesCache.get(fileName)!;
+      return json ? JSON.parse(cached) : cached;
+    }
+
+    // ...cache miss, read from filesystem
     const filePath = join(this.internalFolder, fileName);
-    return readFile(filePath, 'utf8');
+    const content = json
+      ? await readJsonFile(filePath)
+      : await readFile(filePath, 'utf8');
+
+    // Update cache
+    const contentStr =
+      typeof content === 'string' ? content : JSON.stringify(content, null, 2);
+    this.contentFilesCache.set(fileName, contentStr);
+
+    return json ? content : contentStr;
   }
 
   /**
+   * TODO: to be made protected - no direct access to files
    * Shows all file names in the resource.
    * @returns all file names in the resource.
    */
   public async showFileNames(): Promise<string[]> {
+    // Always first check cache...
+    if (this.contentFilesCache.size > 0) {
+      return Array.from(this.contentFilesCache.keys());
+    }
+
+    // ...cache miss, read from filesystem and populate cache
     const files = await readdir(this.internalFolder);
-    return files.filter((file) => VALID_FOLDER_RESOURCE_FILES.includes(file));
+    const validFiles = files.filter((file) =>
+      VALID_FOLDER_RESOURCE_FILES.includes(file),
+    );
+
+    // Update cache by reading all files. Each method call updates specific cache item.
+    for (const fileName of validFiles) {
+      await this.showFile(fileName);
+    }
+
+    return validFiles;
+  }
+
+  /**
+   * 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>) {
+    for (const [fileName, fileContent] of Object.entries(contentFiles)) {
+      await this.updateFile(fileName, fileContent);
+    }
   }
 
   /**
@@ -148,22 +241,59 @@ export class FolderResource extends FileResource {
     if (basename(normalizedFilePath) !== fileName) {
       throw new Error(`File '${fileName}' is not in the resource`);
     }
-    // check if the file is whitelisted
+    // check if the file is allow-listed
     if (!VALID_FOLDER_RESOURCE_FILES.includes(fileName)) {
-      throw new Error(`File '${fileName}' is not whitelisted`);
+      throw new Error(`File '${fileName}' is not allowed`);
     }
 
     await writeFileSafe(filePath, changedContent, { flag: 'w' });
+
+    // Update cache with new content
+    this.contentFilesCache.set(fileName, changedContent);
   }
+
   /**
    * Updates resource.
    * @param key Key to modify
    * @param op Operation to perform on 'key'
+   * @throws if key is unknown.
    */
-  protected async update<Type>(key: string, op: Operation<Type>) {
-    return super.update(key, op);
+  protected async update<Type>(key: UpdateKey, op: Operation<Type>) {
+    if (this.isContentUpdateKey(key)) {
+      const fileName = filename(key.subKey)!;
+      const fileContent = super.handleScalar(op) as string;
+      await this.updateFile(fileName, fileContent);
+      return;
+    }
+
+    const nameChange = key === 'name';
+    const existingName = this.content.name;
+    await super.update(key, op);
+    const content = structuredClone(this.content);
+
+    if (key === 'name') {
+      content.name = super.handleScalar(op) as string;
+    } else if (key === 'displayName') {
+      content.displayName = super.handleScalar(op) as string;
+    } else if (key === 'description') {
+      content.description = super.handleScalar(op) as string;
+    } else {
+      throw new Error(`Unknown property '${key}' for folder resource`);
+    }
+
+    await super.postUpdate(content, key, op);
+
+    if (nameChange) {
+      await this.onNameChange?.(existingName);
+    }
   }
 
+  /**
+   * For handling name changes.
+   * @param previousName The previous name before the change
+   */
+  protected async onNameChange?(previousName: string): Promise<void>;
+
   /**
    * Returns an array of card keys, and/or resource names where this resource is used.
    * @param cards Optional. If defined, only these cards are checked.

package/src/resources/graph-model-resource.ts

@@ -30,7 +30,9 @@ import {
 import type {
   GraphModel,
   GraphModelMetadata,
+  GraphModelUpdateKey,
 } from '../interfaces/resource-interfaces.js';
+import type { GraphModelContent } from '../interfaces/folder-content-interfaces.js';
 import { writeFileSafe } from '../utils/file-utils.js';
 
 /**
@@ -46,8 +48,11 @@ export class GraphModelResource extends FolderResource {
     this.initialize();
   }
 
-  // When resource name changes.
-  private async handleNameChange(existingName: string) {
+  /**
+   * Handle name changes for graph models
+   * @param existingName The previous name before the change
+   */
+  protected async onNameChange(existingName: string): Promise<void> {
     await Promise.all([
       super.updateHandleBars(existingName, this.content.name, [
         await this.calculationFile(),
@@ -122,7 +127,7 @@ export class GraphModelResource extends FolderResource {
   public async rename(newName: ResourceName) {
     const existingName = this.content.name;
     await super.rename(newName);
-    return this.handleNameChange(existingName);
+    return this.onNameChange(existingName);
   }
 
   /**
@@ -130,11 +135,10 @@ export class GraphModelResource extends FolderResource {
    * @returns graph model metadata.
    */
   public async show(): Promise<GraphModel> {
-    const showOnlyFileName = true;
     const baseData = (await super.show()) as GraphModelMetadata;
     return {
       ...baseData,
-      calculationFile: await this.calculationFile(showOnlyFileName),
+      content: (await super.contentData()) as GraphModelContent,
     };
   }
 
@@ -142,32 +146,17 @@ export class GraphModelResource extends FolderResource {
    * Updates graph model resource.
    * @param key Key to modify
    * @param op Operation to perform on 'key'
-   * @throws if key is unknown.
    */
-  public async update<Type>(key: string, op: Operation<Type>) {
-    const nameChange = key === 'name';
-    const existingName = this.content.name;
-
-    await super.update(key, op);
-
-    const content = structuredClone(this.content) as GraphModel;
-
-    if (key === 'name') {
-      content.name = super.handleScalar(op) as string;
-    } else if (key === 'displayName') {
-      content.displayName = super.handleScalar(op) as string;
-    } else if (key === 'description') {
-      content.description = super.handleScalar(op) as string;
-    } else if (key === 'category') {
+  public async update<Type>(key: GraphModelUpdateKey, op: Operation<Type>) {
+    if (key === 'category') {
+      const content = structuredClone(this.content) as GraphModelMetadata;
       content.category = super.handleScalar(op) as string;
-    }
-
-    await super.postUpdate(content, key, op);
 
-    // Renaming this graph model causes that references to its name must be updated.
-    if (nameChange) {
-      await this.handleNameChange(existingName);
+      await super.postUpdate(content, key, op);
+      return;
     }
+
+    await super.update(key, op);
   }
 
   /**

package/src/resources/graph-view-resource.ts

@@ -30,7 +30,9 @@ import {
 import type {
   GraphView,
   GraphViewMetadata,
+  GraphViewUpdateKey,
 } from '../interfaces/resource-interfaces.js';
+import type { GraphViewContent } from '../interfaces/folder-content-interfaces.js';
 
 import { getStaticDirectoryPath } from '@cyberismo/assets';
 import { copyDir } from '../utils/file-utils.js';
@@ -48,15 +50,17 @@ export class GraphViewResource extends FolderResource {
     this.initialize();
   }
 
-  // When resource name changes.
-  private async handleNameChange(existingName: string) {
+  /**
+   * Handle name changes for graph views
+   * @param existingName The previous name before the change
+   */
+  protected async onNameChange(existingName: string): Promise<void> {
     await Promise.all([
       super.updateHandleBars(existingName, this.content.name, [
         await this.handleBarFile(),
       ]),
       super.updateCalculations(existingName, this.content.name),
     ]);
-    // Finally, write updated content.
     await this.write();
   }
 
@@ -118,7 +122,7 @@ export class GraphViewResource extends FolderResource {
   public async rename(newName: ResourceName) {
     const existingName = this.content.name;
     await super.rename(newName);
-    return this.handleNameChange(existingName);
+    return this.onNameChange(existingName);
   }
 
   /**
@@ -126,11 +130,10 @@ export class GraphViewResource extends FolderResource {
    * @returns graph view metadata.
    */
   public async show(): Promise<GraphView> {
-    const showOnlyFileName = true;
     const baseData = (await super.show()) as GraphViewMetadata;
     return {
       ...baseData,
-      handleBarFile: await this.handleBarFile(showOnlyFileName),
+      content: (await super.contentData()) as GraphViewContent,
     };
   }
 
@@ -138,32 +141,17 @@ export class GraphViewResource extends FolderResource {
    * Updates graph view resource.
    * @param key Key to modify
    * @param op Operation to perform on 'key'
-   * @throws if key is unknown.
    */
-  public async update<Type>(key: string, op: Operation<Type>) {
-    const nameChange = key === 'name';
-    const existingName = this.content.name;
-
-    await super.update(key, op);
-
-    const content = structuredClone(this.content) as GraphView;
-
-    if (key === 'name') {
-      content.name = super.handleScalar(op) as string;
-    } else if (key === 'displayName') {
-      content.displayName = super.handleScalar(op) as string;
-    } else if (key === 'description') {
-      content.description = super.handleScalar(op) as string;
-    } else if (key === 'category') {
+  public async update<Type>(key: GraphViewUpdateKey, op: Operation<Type>) {
+    if (key === 'category') {
+      const content = structuredClone(this.content) as GraphViewMetadata;
       content.category = super.handleScalar(op) as string;
-    }
-
-    await super.postUpdate(content, key, op);
 
-    // Renaming this graph view causes that references to its name must be updated.
-    if (nameChange) {
-      await this.handleNameChange(existingName);
+      await super.postUpdate(content, key, op);
+      return;
     }
+
+    await super.update(key, op);
   }
 
   /**

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

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