@cyberismo/data-handler 0.0.12 → 0.0.14

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.
+   */
+  protected async updateContentFiles(contentFiles: Record<string, string>) {
+    for (const [fileName, fileContent] of Object.entries(contentFiles)) {
+      await this.updateFile(fileName, fileContent);
+    }
   }
 
   /**
@@ -134,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
@@ -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') {

package/src/resources/report-resource.ts

@@ -1,43 +1,46 @@
 /**
   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 { readdir, readFile } from 'node:fs/promises';
+import { readdir } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { extname, join } from 'node:path';
 
 import { copyDir } from '../utils/file-utils.js';
-import type {
-  Card,
-  Operation,
-  Project,
-  ResourceName,
-} from './folder-resource.js';
 import {
   DefaultContent,
   FolderResource,
   resourceNameToString,
   sortCards,
 } from './folder-resource.js';
+import { getStaticDirectoryPath } from '@cyberismo/assets';
+import { filename } from '../interfaces/folder-content-interfaces.js';
+import { Validate } from '../commands/validate.js';
+
+import type {
+  Card,
+  Operation,
+  Project,
+  ResourceName,
+} from './folder-resource.js';
 import type {
   Report,
   ReportMetadata,
+  ReportUpdateKey,
 } from '../interfaces/resource-interfaces.js';
+import type { ReportContent } from '../interfaces/folder-content-interfaces.js';
 import type { Schema } from 'jsonschema';
-import { getStaticDirectoryPath } from '@cyberismo/assets';
-import { Validate } from '../commands/validate.js';
 
-const CARD_CONTENT_HANDLEBAR_FILE = 'index.adoc.hbs';
-const QUERY_HANDLEBAR_FILE = 'query.lp.hbs';
 const REPORT_SCHEMA_FILE = 'parameterSchema.json';
 const PARAMETER_SCHEMA_ID = 'jsonSchema';
 
@@ -67,8 +70,21 @@ export class ReportResource extends FolderResource {
     'defaultReport',
   );
 
-  // When resource name changes.
-  private async handleNameChange(existingName: string) {
+  // Try to read schema file content
+  private readSchemaFile(path: string) {
+    try {
+      const schema = readFileSync(path);
+      return JSON.parse(schema.toString());
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Handle name changes for reports
+   * @param existingName The previous name before the change
+   */
+  protected async onNameChange(existingName: string): Promise<void> {
     await Promise.all([
       super.updateHandleBars(
         existingName,
@@ -81,16 +97,6 @@ export class ReportResource extends FolderResource {
     await this.write();
   }
 
-  // Try to read schema file content
-  private readSchemaFile(path: string) {
-    try {
-      const schema = readFileSync(path);
-      return JSON.parse(schema.toString());
-    } catch {
-      return undefined;
-    }
-  }
-
   /**
    * Sets new metadata into the report object.
    * @param newContent metadata content for the report.
@@ -143,7 +149,7 @@ export class ReportResource extends FolderResource {
   public async rename(newName: ResourceName) {
     const existingName = this.content.name;
     await super.rename(newName);
-    return this.handleNameChange(existingName);
+    return this.onNameChange(existingName);
   }
 
   /**
@@ -151,19 +157,16 @@ export class ReportResource extends FolderResource {
    * @returns report metadata.
    */
   public async show(): Promise<Report> {
-    const reportMetadata = (await super.show()) as ReportMetadata;
+    const baseData = (await super.show()) as ReportMetadata;
+    const fileContents = await super.contentData();
+    const content: ReportContent = {
+      contentTemplate: fileContents.contentTemplate as string,
+      queryTemplate: fileContents.queryTemplate as string,
+      schema: fileContents.schema ? (fileContents.schema as Schema) : undefined,
+    };
     return {
-      name: resourceNameToString(this.resourceName),
-      displayName: reportMetadata.displayName,
-      description: reportMetadata.description,
-      metadata: reportMetadata,
-      contentTemplate: (
-        await readFile(join(this.internalFolder, CARD_CONTENT_HANDLEBAR_FILE))
-      ).toString(),
-      queryTemplate: (
-        await readFile(join(this.internalFolder, QUERY_HANDLEBAR_FILE))
-      ).toString(),
-      schema: this.reportSchema,
+      ...baseData,
+      content: content,
     };
   }
 
@@ -171,32 +174,27 @@ export class ReportResource extends FolderResource {
    * Updates report 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 ReportMetadata;
-
-    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') {
-      content.category = super.handleScalar(op) as string;
+  public async update<Type>(key: ReportUpdateKey, op: Operation<Type>) {
+    if (
+      typeof key === 'object' &&
+      key.key === 'content' &&
+      key.subKey === 'schema'
+    ) {
+      const fileContent = JSON.stringify(super.handleScalar(op), null, 2);
+      await this.updateFile(filename(key.subKey)!, fileContent);
+      return;
     }
 
-    await super.postUpdate(content, key, op);
+    if (key === 'category') {
+      const content = structuredClone(this.content) as ReportMetadata;
+      content.category = super.handleScalar(op) as string;
 
-    // Renaming this report 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);
   }
 
   /**