@cyberismo/data-handler 0.0.14 → 0.0.15

package/src/resources/folder-resource.ts

@@ -16,13 +16,12 @@ 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,
+import type { ResourceBaseMetadata } from '../interfaces/resource-interfaces.js';
+import {
+  isContentKey,
+  type UpdateKey,
 } from '../interfaces/resource-interfaces.js';
 import type { ResourceFolderType } from '../interfaces/project-interfaces.js';
-import type { Schema } from 'jsonschema';
 
 import {
   DefaultContent,
@@ -32,13 +31,16 @@ import {
   resourceNameToString,
   sortCards,
 } from './file-resource.js';
+import type { FolderResourceContent } from '../interfaces/folder-content-interfaces.js';
 import {
   filename,
   propertyName,
 } from '../interfaces/folder-content-interfaces.js';
-import { readJsonFile } from '../utils/json.js';
+import { formatJson, readJsonFile } from '../utils/json.js';
 import { VALID_FOLDER_RESOURCE_FILES } from '../utils/constants.js';
 import { writeFileSafe } from '../utils/file-utils.js';
+import type { ShowReturnType } from './resource-object.js';
+import { ResourceObject } from './resource-object.js';
 
 export {
   type Card,
@@ -54,7 +56,10 @@ export {
 /**
  * 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 = '';
 
   // Cache for content files to avoid repeated filesystem operations. Content is stored as string.
@@ -62,6 +67,7 @@ export class FolderResource extends FileResource {
 
   constructor(project: Project, name: ResourceName, type: ResourceFolderType) {
     super(project, name, type);
+    this.initialize();
   }
 
   // Clears the content files cache.
@@ -69,65 +75,15 @@ export class FolderResource extends FileResource {
     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.
    */
-  protected async create(newContent?: ResourceContent) {
+  protected async create(newContent?: T) {
     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.
    */
@@ -140,6 +96,12 @@ export class FolderResource extends FileResource {
     );
   }
 
+  /**
+   * For handling name changes.
+   * @param previousName The previous name before the change
+   */
+  protected abstract onNameChange?(previousName: string): Promise<void>;
+
   /**
    * Renames resource metadata file and renames memory resident object 'name'.
    * @param newName New name for the resource.
@@ -149,21 +111,12 @@ export class FolderResource extends FileResource {
   }
 
   /**
-   * 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.
    */
-  public async showFile(
+  protected async showFile(
     fileName: string,
     json: boolean = false,
   ): Promise<string> {
@@ -181,18 +134,17 @@ export class FolderResource extends FileResource {
 
     // Update cache
     const contentStr =
-      typeof content === 'string' ? content : JSON.stringify(content, null, 2);
+      typeof content === 'string' ? content : formatJson(content);
     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[]> {
+  protected async showFileNames(): Promise<string[]> {
     // Always first check cache...
     if (this.contentFilesCache.size > 0) {
       return Array.from(this.contentFilesCache.keys());
@@ -212,16 +164,6 @@ export class FolderResource extends FileResource {
     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);
-    }
-  }
-
   /**
    * Updates a file in the resource.
    * @param fileName The name of the file to update.
@@ -243,7 +185,7 @@ 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' });
@@ -252,23 +194,80 @@ export class FolderResource extends FileResource {
     this.contentFilesCache.set(fileName, 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 async contentData(): Promise<U> {
+    const fileNames = await this.showFileNames();
+    const content = {} as Record<string, unknown>;
+
+    for (const fileName of fileNames) {
+      const name = propertyName(fileName);
+      if (name) {
+        const JSONFile = name === 'schema';
+        content[name] = await this.showFile(fileName, JSONFile);
+      }
+    }
+
+    // TODO: Instead of casting, validate that content matches U
+    // This requires a runtime schema for U to be defined(via an abstract variable)
+
+    return content as U;
+  }
+
+  /**
+   * Deletes file and content folder from disk and clears out the memory resident object.
+   * @throws if resource is a module resource or does not exist or is used by other resources.
+   */
+  public async delete() {
+    await super.delete();
+    await rm(this.internalFolder, { recursive: true, force: true });
+    this.clearContentCache();
+  }
+
   /**
    * 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,7 +280,7 @@ 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);
@@ -289,40 +288,15 @@ export class FolderResource extends FileResource {
   }
 
   /**
-   * 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.
+   * Shows metadata of the resource and content of the resource.
+   * @returns resource type's metadata and content.
+   * @throws if resource does not exist.
    */
-  protected async validate(content?: object) {
-    return super.validate(content);
+  public async show(): Promise<ShowReturnType<T, U>> {
+    this.assertResourceExists();
+    return {
+      ...this.content,
+      content: await this.contentData(),
+    };
   }
 }

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

@@ -12,8 +12,7 @@
   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 type {
   Card,
@@ -28,9 +27,8 @@ import {
   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';
@@ -38,14 +36,15 @@ import { writeFileSafe } from '../utils/file-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 +54,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, 'model.lp'),
       ]),
       super.updateCalculations(existingName, this.content.name),
     ]);
@@ -90,36 +89,6 @@ export class GraphModelResource extends FolderResource {
     );
   }
 
-  /**
-   * 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)!;
-  }
-
   /**
    * Renames the object and the file.
    * @param newName New name for the resource.
@@ -130,33 +99,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 +127,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();
-  }
 }

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

@@ -28,9 +28,8 @@ import {
   sortCards,
 } from './folder-resource.js';
 import type {
-  GraphView,
   GraphViewMetadata,
-  GraphViewUpdateKey,
+  UpdateKey,
 } from '../interfaces/resource-interfaces.js';
 import type { GraphViewContent } from '../interfaces/folder-content-interfaces.js';
 
@@ -40,14 +39,15 @@ import { copyDir } from '../utils/file-utils.js';
 /**
  * Graph view resource class.
  */
-export class GraphViewResource extends FolderResource {
+export class GraphViewResource extends FolderResource<
+  GraphViewMetadata,
+  GraphViewContent
+> {
   constructor(project: Project, name: ResourceName) {
     super(project, name, 'graphViews');
 
     this.contentSchemaId = 'graphViewSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
-
-    this.initialize();
   }
 
   /**
@@ -85,20 +85,6 @@ export class GraphViewResource extends FolderResource {
     );
   }
 
-  /**
-   * Returns resource content.
-   */
-  public get data(): GraphView {
-    return super.data as GraphView;
-  }
-
-  /**
-   * Deletes file and folder that this resource is based on.
-   */
-  public async delete() {
-    return super.delete();
-  }
-
   /**
    * Returns handlebar filename that this graph view has.
    * @returns handlebar filename that this graph view has.
@@ -125,33 +111,24 @@ export class GraphViewResource extends FolderResource {
     return this.onNameChange(existingName);
   }
 
-  /**
-   * Shows metadata of the resource.
-   * @returns graph view metadata.
-   */
-  public async show(): Promise<GraphView> {
-    const baseData = (await super.show()) as GraphViewMetadata;
-    return {
-      ...baseData,
-      content: (await super.contentData()) as GraphViewContent,
-    };
-  }
-
   /**
    * Updates graph view resource.
-   * @param key Key to modify
+   * @param updateKey Key to modify
    * @param op Operation to perform on 'key'
    */
-  public async update<Type>(key: GraphViewUpdateKey, op: Operation<Type>) {
-    if (key === 'category') {
+  public async update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    if (updateKey.key === 'category') {
       const content = structuredClone(this.content) as GraphViewMetadata;
       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);
   }
 
   /**
@@ -162,28 +139,11 @@ export class GraphViewResource 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 graph view.
-   * @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 view's folder and handlebar file.
-   */
-  public async write() {
-    await super.write();
-  }
 }