@cyberismo/data-handler 0.0.14 → 0.0.16

package/src/resources/folder-resource.ts

@@ -15,119 +15,59 @@
 import { basename, dirname, join, normalize } from 'node:path';
 import { mkdir, readdir, readFile, rename, rm } from 'node:fs/promises';
 
-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 {
-  DefaultContent,
-  FileResource,
-  Project,
-  resourceName,
-  resourceNameToString,
-  sortCards,
-} from './file-resource.js';
+import { isContentKey } from '../interfaces/resource-interfaces.js';
 import {
   filename,
-  propertyName,
+  contentPropertyName,
 } from '../interfaces/folder-content-interfaces.js';
-import { readJsonFile } from '../utils/json.js';
+import { formatJson } from '../utils/json.js';
 import { VALID_FOLDER_RESOURCE_FILES } from '../utils/constants.js';
 import { writeFileSafe } from '../utils/file-utils.js';
+import { ResourceObject } from './resource-object.js';
+import { resourceName } from '../utils/resource-utils.js';
 
-export {
-  type Card,
-  DefaultContent,
-  FileResource,
-  type Operation,
-  Project,
-  ResourceName,
-  resourceNameToString,
-  sortCards,
-};
+import type { UpdateKey } from '../interfaces/resource-interfaces.js';
+import type { FolderResourceContent } from '../interfaces/folder-content-interfaces.js';
+import type { Operation } from './resource-object.js';
+import type { Project } from '../containers/project.js';
+import type { ResourceFolderType } from '../interfaces/project-interfaces.js';
+import type { ResourceBaseMetadata } from '../interfaces/resource-interfaces.js';
+import type { ResourceName } from '../utils/resource-utils.js';
+import type { ShowReturnType } from './resource-object.js';
 
 /**
- * Folder type resource class. These are resources that have their own folders for content.
+ * Folder type resource class.
+ * These are resources that have their own folders for content.
  */
-export class FolderResource extends FileResource {
+export abstract class FolderResource<
+  T extends ResourceBaseMetadata,
+  U extends FolderResourceContent,
+> extends ResourceObject<T, U> {
   protected internalFolder: string = '';
+  private resourceContent: U = {} as U;
 
-  // Cache for content files to avoid repeated filesystem operations. Content is stored as string.
-  private contentFilesCache = new Map<string, string>();
-
+  /**
+   * Constructs a FolderResource object.
+   * @param project Project in which this resource exists.
+   * @param name Name for the resource.
+   * @param type Type for this resource.
+   */
   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;
+    this.initialize();
   }
 
   /**
    * Creates a new folder type object. Base class writes the object to disk automatically.
    * @param newContent Content for the type.
    */
-  protected async create(newContent?: ResourceContent) {
+  protected async create(newContent?: T) {
+    // Validate resource identifier before creating on disk
+    this.validateResourceIdentifier();
     await super.create(newContent);
     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.
-   */
-  public get data() {
-    return super.data;
-  }
-
-  /**
-   * Deletes file(s) from disk and clears out the memory resident object.
-   */
-  protected async delete() {
-    await super.delete();
-    await rm(this.internalFolder, { recursive: true, force: true });
-    this.clearContentCache();
-  }
-
-  // Get (resource folder) type name
-  protected get getType() {
-    return super.getType;
-  }
-
-  // Get logger instance
-  protected get logger() {
-    return super.getLogger(this.getType);
-  }
-
   /**
    * Initialize the resource item.
    */
@@ -141,85 +81,42 @@ export class FolderResource extends FileResource {
   }
 
   /**
-   * Renames resource metadata file and renames memory resident object 'name'.
-   * @param newName New name for the resource.
-   */
-  protected async rename(newName: ResourceName) {
-    return super.rename(newName);
-  }
-
-  /**
-   * Shows metadata of the resource.
-   * @returns resource type's metadata.
-   */
-  protected async show(): Promise<ResourceContent> {
-    return super.show();
-  }
-
-  /**
-   * 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.
+   * For handling name changes.
+   * @param previousName The previous name before the change
    */
-  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);
-    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;
-  }
+  protected abstract onNameChange?(previousName: string): Promise<void>;
 
   /**
-   * TODO: to be made protected - no direct access to files
-   * Shows all file names in the resource.
-   * @returns all file names in the resource.
+   * Set content files. Should not be called by others than resource cache.
    */
-  public async showFileNames(): Promise<string[]> {
-    // Always first check cache...
-    if (this.contentFilesCache.size > 0) {
-      return Array.from(this.contentFilesCache.keys());
-    }
+  public setContentFiles(contentFiles: Map<string, string>) {
+    const content = {} as Record<string, unknown>;
 
-    // ...cache miss, read from filesystem and populate cache
-    const files = await readdir(this.internalFolder);
-    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);
+    for (const [fileName, fileContent] of contentFiles.entries()) {
+      const key = contentPropertyName(fileName);
+      if (key) {
+        const isJson = key === 'schema';
+        content[key] = isJson ? JSON.parse(fileContent) : fileContent;
+      }
     }
 
-    return validFiles;
+    this.resourceContent = content as U;
   }
 
   /**
-   * Updates content files from a content object.
-   * @param contentFiles Object with file names as keys and file contents as values.
+   * Load all content files from the internal folder and set them.
    */
-  protected async updateContentFiles(contentFiles: Record<string, string>) {
-    for (const [fileName, fileContent] of Object.entries(contentFiles)) {
-      await this.updateFile(fileName, fileContent);
+  protected async loadContentFiles() {
+    const contentFiles = new Map<string, string>();
+    const files = await readdir(this.internalFolder, { withFileTypes: true });
+    for (const file of files) {
+      if (file.isFile() && VALID_FOLDER_RESOURCE_FILES.includes(file.name)) {
+        const filePath = join(this.internalFolder, file.name);
+        const content = await readFile(filePath, 'utf-8');
+        contentFiles.set(file.name, content);
+      }
     }
+    this.setContentFiles(contentFiles);
   }
 
   /**
@@ -227,7 +124,7 @@ export class FolderResource extends FileResource {
    * @param fileName The name of the file to update.
    * @param changedContent The new content for the file.
    */
-  protected async updateFile(fileName: string, changedContent: string) {
+  public async updateFile(fileName: string, changedContent: string) {
     const filePath = join(this.internalFolder, fileName);
 
     // Do not allow updating file in other directories
@@ -243,32 +140,96 @@ export class FolderResource extends FileResource {
     }
     // check if the file is allow-listed
     if (!VALID_FOLDER_RESOURCE_FILES.includes(fileName)) {
-      throw new Error(`File '${fileName}' is not allowed`);
+      throw new Error(`File '${fileName}' is not allowed to be updated`);
     }
 
     await writeFileSafe(filePath, changedContent, { flag: 'w' });
 
-    // Update cache with new content
-    this.contentFilesCache.set(fileName, changedContent);
+    // Update this resource's content
+    const key = contentPropertyName(fileName);
+    if (key) {
+      const isJson = key === 'schema';
+      (this.resourceContent as Record<string, unknown>)[key] = isJson
+        ? JSON.parse(changedContent)
+        : changedContent;
+    }
+  }
+
+  /**
+   * Writes resource content to disk.
+   */
+  protected async write() {
+    const folderName = basename(this.internalFolder);
+
+    // Check if "name" has changed. Changing "name" means renaming the file.
+    const nameInContent = resourceName(this.content.name).identifier;
+    if (folderName !== nameInContent) {
+      const newFolderName = join(this.resourceFolder, nameInContent);
+      await rename(this.internalFolder, newFolderName);
+      this.internalFolder = newFolderName;
+    }
+    return super.write();
+  }
+
+  /**
+   * Gets content of all files to properties.
+   * @returns object with property names as keys and file contents as values.
+   */
+  public contentData(): U {
+    // TODO: Instead of casting, validate that content matches U
+    // This requires a runtime schema for U to be defined(via an abstract variable)
+
+    return this.resourceContent;
+  }
+
+  /**
+   * Deletes file and content folder from disk and clears out the memory resident object.
+   */
+  public async delete() {
+    await super.delete();
+    await rm(this.internalFolder, { recursive: true, force: true });
+  }
+
+  /**
+   * Shows metadata of the resource and content of the resource.
+   * @template T Resource type
+   * @template U Resource content
+   * @returns resource type's metadata and content.
+   */
+  public show(): ShowReturnType<T, U> {
+    this.assertResourceExists();
+    return {
+      ...this.content,
+      content: this.contentData(),
+    };
   }
 
   /**
    * Updates resource.
-   * @param key Key to modify
+   * @param updateKey Key to modify
    * @param op Operation to perform on 'key'
    * @throws if key is unknown.
    */
-  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);
+  public async update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    const { key } = updateKey;
+    if (isContentKey(updateKey)) {
+      const fileName = filename(updateKey.subKey)!;
+      const fileContent = super.handleScalar(op);
+      const fileContentString =
+        typeof fileContent === 'string'
+          ? fileContent
+          : formatJson(fileContent as object); // TODO: Fix operation types. In practice, content files are either strings or objects
+
+      await this.updateFile(fileName, fileContentString);
       return;
     }
 
     const nameChange = key === 'name';
     const existingName = this.content.name;
-    await super.update(key, op);
+    await super.update(updateKey, op);
     const content = structuredClone(this.content);
 
     if (key === 'name') {
@@ -281,48 +242,10 @@ export class FolderResource extends FileResource {
       throw new Error(`Unknown property '${key}' for folder resource`);
     }
 
-    await super.postUpdate(content, key, op);
+    await super.postUpdate(content, updateKey, 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.
-   * @returns an array of card keys, and/or resource names where this resource is used.
-   */
-  protected async usage(cards?: Card[]): Promise<string[]> {
-    return super.usage(cards);
-  }
-
-  /**
-   * Writes resource content to disk.
-   */
-  protected async write() {
-    const folderName = basename(this.internalFolder);
-
-    // Check if "name" has changed. Changing "name" means renaming the file.
-    const nameInContent = resourceName(this.content.name).identifier;
-    if (folderName !== nameInContent) {
-      const newFolderName = join(this.resourceFolder, nameInContent);
-      await rename(this.internalFolder, newFolderName);
-      this.internalFolder = newFolderName;
-    }
-    return super.write();
-  }
-
-  /**
-   * Validates the resource. If object is invalid, throws.
-   */
-  protected async validate(content?: object) {
-    return super.validate(content);
-  }
 }

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

@@ -12,40 +12,37 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { readdir } from 'node:fs/promises';
-import { extname, join } from 'node:path';
+import { join } from 'node:path';
 
+import { DefaultContent } from './create-defaults.js';
+import { FolderResource } from './folder-resource.js';
+import { resourceNameToString } from '../utils/resource-utils.js';
+import { sortCards } from '../utils/card-utils.js';
+import { writeFileSafe } from '../utils/file-utils.js';
+import { CONTENT_FILES } from '../interfaces/folder-content-interfaces.js';
+
+import type { Card } from '../interfaces/project-interfaces.js';
 import type {
-  Card,
-  Operation,
-  Project,
-  ResourceName,
-} from './folder-resource.js';
-import {
-  DefaultContent,
-  FolderResource,
-  resourceNameToString,
-  sortCards,
-} from './folder-resource.js';
-import type {
-  GraphModel,
   GraphModelMetadata,
-  GraphModelUpdateKey,
+  UpdateKey,
 } from '../interfaces/resource-interfaces.js';
 import type { GraphModelContent } from '../interfaces/folder-content-interfaces.js';
-import { writeFileSafe } from '../utils/file-utils.js';
+import type { Operation } from './resource-object.js';
+import type { Project } from '../containers/project.js';
+import type { ResourceName } from '../utils/resource-utils.js';
 
 /**
  * Graph model resource class.
  */
-export class GraphModelResource extends FolderResource {
+export class GraphModelResource extends FolderResource<
+  GraphModelMetadata,
+  GraphModelContent
+> {
   constructor(project: Project, name: ResourceName) {
     super(project, name, 'graphModels');
 
     this.contentSchemaId = 'graphModelSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
-
-    this.initialize();
   }
 
   /**
@@ -55,7 +52,7 @@ export class GraphModelResource extends FolderResource {
   protected async onNameChange(existingName: string): Promise<void> {
     await Promise.all([
       super.updateHandleBars(existingName, this.content.name, [
-        await this.calculationFile(),
+        join(this.internalFolder, CONTENT_FILES.model),
       ]),
       super.updateCalculations(existingName, this.content.name),
     ]);
@@ -80,44 +77,14 @@ export class GraphModelResource extends FolderResource {
     await super.create(newContent);
 
     // Create the internal folder in 'create', instead of 'write'.
-    const calculationsFile = join(this.internalFolder, 'model.lp');
-    await writeFileSafe(
-      calculationsFile,
-      `% add your calculations here for '${this.resourceName.identifier}'`,
-      {
-        flag: 'wx',
-      },
-    );
-  }
-
-  /**
-   * Returns resource content.
-   */
-  public get data(): GraphModel {
-    return super.data as GraphModel;
-  }
-
-  /**
-   * Deletes file and folder that this resource is based on.
-   */
-  public async delete() {
-    return super.delete();
-  }
-
-  /**
-   * Returns calculation file that this graph model has.
-   * @returns calculation file name that this graph model has.
-   */
-  public async calculationFile(nameOnly: boolean = false): Promise<string> {
-    return (
-      await readdir(this.internalFolder, {
-        withFileTypes: true,
-        recursive: true,
-      })
-    )
-      .filter((dirent) => dirent.isFile() && extname(dirent.name) === '.lp')
-      .map((item) => (nameOnly ? item.name : join(item.parentPath, item.name)))
-      .at(0)!;
+    const modelContent = `% add your calculations here for '${this.resourceName.identifier}'`;
+    const modelFile = CONTENT_FILES.model;
+    const calculationsFile = join(this.internalFolder, modelFile);
+    await writeFileSafe(calculationsFile, modelContent, {
+      flag: 'wx',
+    });
+
+    await this.loadContentFiles();
   }
 
   /**
@@ -130,33 +97,24 @@ export class GraphModelResource extends FolderResource {
     return this.onNameChange(existingName);
   }
 
-  /**
-   * Shows metadata of the resource.
-   * @returns graph model metadata.
-   */
-  public async show(): Promise<GraphModel> {
-    const baseData = (await super.show()) as GraphModelMetadata;
-    return {
-      ...baseData,
-      content: (await super.contentData()) as GraphModelContent,
-    };
-  }
-
   /**
    * Updates graph model resource.
-   * @param key Key to modify
+   * @param updateKey Key to modify
    * @param op Operation to perform on 'key'
    */
-  public async update<Type>(key: GraphModelUpdateKey, op: Operation<Type>) {
-    if (key === 'category') {
-      const content = structuredClone(this.content) as GraphModelMetadata;
+  public async update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    if (updateKey.key === 'category') {
+      const content = structuredClone(this.content);
       content.category = super.handleScalar(op) as string;
 
-      await super.postUpdate(content, key, op);
+      await super.postUpdate(content, updateKey, op);
       return;
     }
 
-    await super.update(key, op);
+    await super.update(updateKey, op);
   }
 
   /**
@@ -167,28 +125,11 @@ export class GraphModelResource extends FolderResource {
    * @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 allCards = cards ?? super.cards();
     const [relevantCards, calculations] = await Promise.all([
       super.usage(allCards),
       super.calculations(),
     ]);
     return [...relevantCards.sort(sortCards), ...calculations];
   }
-
-  /**
-   * Validates graphModel.
-   * @throws when there are validation errors.
-   * @param content Content to be validated.
-   * @note If content is not provided, base class validation will use resource's current content.
-   */
-  public async validate(content?: object) {
-    return super.validate(content);
-  }
-
-  /**
-   *  Create the graph model's folder and calculation file.
-   */
-  public async write() {
-    await super.write();
-  }
 }