@cyberismo/data-handler 0.0.14 → 0.0.15

package/src/resources/resource-object.ts

@@ -13,21 +13,38 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 
 // node
-import { readFile, writeFile } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { basename, join, sep } from 'node:path';
 
 import { hasCode } from '../utils/error-utils.js';
 
 import { ArrayHandler } from './array-handler.js';
 import type {
   Card,
+  Resource,
   ResourceFolderType,
 } from '../interfaces/project-interfaces.js';
 import type { Logger } from 'pino';
-import { type Project, ResourcesFrom } from '../containers/project.js';
-import type { ResourceContent } from '../interfaces/resource-interfaces.js';
-import type { ResourceName } from '../utils/resource-utils.js';
+import type { Project } from '../containers/project.js';
+import { ResourcesFrom } from '../containers/project/resource-collector.js';
+import type {
+  ResourceBaseMetadata,
+  UpdateKey,
+} from '../interfaces/resource-interfaces.js';
+import type { Validate } from '../commands/validate.js';
+import {
+  resourceName,
+  resourceNameToPath,
+  resourceNameToString,
+  type ResourceName,
+} from '../utils/resource-utils.js';
 import { getChildLogger } from '../utils/log-utils.js';
+import { deleteFile, pathExists } from '../utils/file-utils.js';
+import {
+  readJsonFile,
+  readJsonFileSync,
+  writeJsonFile,
+} from '../utils/json.js';
 
 // Possible operations to perform when doing "update"
 export type UpdateOperations = 'add' | 'change' | 'rank' | 'remove';
@@ -80,18 +97,29 @@ export type OperationMap<T> = {
 // Given an operation name, get the corresponding operation type
 export type OperationFor<T, N extends UpdateOperations> = OperationMap<T>[N];
 
+// T, but U is in the content field
+export type ShowReturnType<T extends ResourceBaseMetadata, U = never> = Omit<
+  T,
+  'content'
+> & {
+  [K in 'content' as [U] extends [never] ? never : K]: U;
+};
+
 /**
  * Abstract class for resources.
  */
-export abstract class AbstractResource {
+export abstract class AbstractResource<
+  T extends ResourceBaseMetadata,
+  U = never, // determines type returned by show()
+> {
   protected abstract calculate(): Promise<void>; // update resource specific calculations
-  protected abstract create(content?: ResourceContent): Promise<void>; // create a new with the content (memory)
+  protected abstract create(content?: T): Promise<void>; // create a new with the content (memory)
   protected abstract delete(): Promise<void>; // delete from disk
   protected abstract read(): Promise<void>; // read content from disk (replaces existing content, if any)
   protected abstract rename(newName: ResourceName): Promise<void>; // change name of the resource and filename; same as update('name', ...)
-  protected abstract show(): Promise<ResourceContent>; // return the content as JSON
-  protected abstract update<Type>(
-    key: string,
+  protected abstract show(): Promise<ShowReturnType<T, U>>; // return the content as JSON
+  protected abstract update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
     operation: Operation<Type>,
   ): Promise<void>; // change one key of resource
   protected abstract usage(cards?: Card[]): Promise<string[]>; // list of card keys or resource names where this resource is used in
@@ -102,47 +130,125 @@ export abstract class AbstractResource {
   protected abstract getLogger(loggerName: string): Logger;
 }
 
-/**
- * Base class for all resources.
- */
-export class ResourceObject extends AbstractResource {
+type ValidateInstance = InstanceType<typeof Validate>;
+
+export abstract class ResourceObject<
+  T extends ResourceBaseMetadata,
+  U,
+> extends AbstractResource<T, U> {
+  // TODO: Remove when INTDEV-1048 is implemented, since caching is done at object level
+  private cache: Map<string, JSON>;
+  private static validateInstancePromise?: Promise<ValidateInstance>;
+
+  protected content: T;
   protected moduleResource: boolean;
   protected contentSchema: JSON = {} as JSON;
   protected contentSchemaId: string = '';
   protected type: ResourceFolderType = '' as ResourceFolderType;
   protected resourceFolder: string = '';
+  protected logger: Logger;
+
+  /**
+   * Path to the resource metadata file (the .json file).
+   */
+  public fileName: string = '';
 
   constructor(
     protected project: Project,
     protected resourceName: ResourceName,
+    type: ResourceFolderType,
   ) {
     super();
     this.moduleResource =
       this.resourceName.prefix !== this.project.projectPrefix;
+    this.cache = this.project.resourceCache;
+    this.type = type;
+    this.logger = this.getLogger(this.getType);
+    this.content = { name: '' } as T; // not found if name is empty
   }
 
-  protected async calculate() {}
-  protected async create(_content?: ResourceContent) {}
-  protected async delete() {}
-  protected async read() {}
-  protected async rename(_name: ResourceName) {}
-  protected async show(): Promise<ResourceContent> {
-    return {} as ResourceContent;
+  private static async getValidate(): Promise<ValidateInstance> {
+    // a bit hacky solution to avoid circular dependencies
+    if (!this.validateInstancePromise) {
+      this.validateInstancePromise = import('../commands/validate.js').then(
+        ({ Validate }) => Validate.getInstance(),
+      );
+    }
+    return this.validateInstancePromise;
   }
-  protected get getType(): string {
+
+  private resourceObjectToResource(): Resource {
+    return {
+      name: this.data ? this.data.name : '',
+      path: this.fileName.substring(0, this.fileName.lastIndexOf(sep)),
+    };
+  }
+
+  // Type of resource.
+  private resourceType(): ResourceFolderType {
     return this.type;
   }
-  protected getLogger(loggerName: string): Logger {
-    return getChildLogger({
-      module: loggerName,
-    });
+
+  private toCache() {
+    this.cache.set(
+      resourceNameToString(this.resourceName),
+      this.content as unknown as JSON,
+    );
+  }
+
+  /**
+   * Checks if resource exists
+   * @throws if resource does not exist
+   */
+  protected assertResourceExists() {
+    if (!pathExists(this.fileName)) {
+      const resourceType = `${this.type[0].toUpperCase()}${this.type.slice(1, this.type.length - 1)}`;
+      const name = resourceNameToString(this.resourceName);
+      throw new Error(
+        `${resourceType} '${name}' does not exist in the project`,
+      );
+    }
+  }
+
+  protected async calculate() {}
+
+  // Calculations that use this resource.
+  protected async calculations(): Promise<string[]> {
+    const references: string[] = [];
+    const resourceName = resourceNameToString(this.resourceName);
+    for (const calculation of await this.project.calculations(
+      ResourcesFrom.all,
+    )) {
+      const fileNameWithExtension = calculation.name.endsWith('.lp')
+        ? calculation.name
+        : calculation.name + '.lp';
+      const filename = join(calculation.path, basename(fileNameWithExtension));
+      try {
+        const content = await readFile(filename, 'utf-8');
+        if (content.includes(resourceName)) {
+          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}`,
+        );
+      }
+    }
+    return references;
   }
-  protected async update<Type>(_key: string, _op: Operation<Type>) {}
-  protected async usage(_cards?: Card[]): Promise<string[]> {
-    return [];
+
+  // Cards from project.
+  protected cards(): Card[] {
+    return [
+      ...this.project.cards(undefined),
+      ...this.project.allTemplateCards(),
+    ];
   }
-  protected async validate(_content?: object) {}
-  protected async write() {}
 
   /**
    * Returns .schema content file.
@@ -158,6 +264,59 @@ export class ResourceObject extends AbstractResource {
     ] as unknown as JSON;
   }
 
+  // Creates resource.
+  protected async create(newContent?: T) {
+    if (pathExists(this.fileName)) {
+      throw new Error(
+        `Resource '${this.resourceName.identifier}' already exists in the project`,
+      );
+    }
+
+    if (this.resourceFolder === '') {
+      this.resourceName = resourceName(
+        `${this.project.projectPrefix}/${this.type}/${this.resourceName.identifier}`,
+      );
+      this.resourceFolder = this.project.paths.resourcePath(
+        this.resourceName.type as ResourceFolderType,
+      );
+    }
+
+    const validator = await ResourceObject.getValidate();
+    const validName = validator.validResourceName(
+      this.resourceType(),
+      resourceNameToString(this.resourceName),
+      await this.project.projectPrefixes(),
+    );
+
+    let validContent = {} as T;
+    if (newContent) {
+      validContent = newContent;
+      validContent.name = validName;
+    } else {
+      validContent.description = '';
+      validContent.displayName = '';
+    }
+
+    this.content = validContent;
+    await this.write();
+
+    // Notify project & collector
+    this.project.addResource(
+      this.resourceObjectToResource(),
+      this.content as unknown as JSON,
+    );
+  }
+
+  protected getLogger(loggerName: string): Logger {
+    return getChildLogger({
+      module: loggerName,
+    });
+  }
+
+  protected get getType(): string {
+    return this.type;
+  }
+
   /**
    * Handles operation to an array.
    * @param operation Operation to perform on array.
@@ -197,7 +356,142 @@ export class ResourceObject extends AbstractResource {
     ) {
       throw new Error(`Cannot do operation ${operation.name} on scalar value`);
     }
-    return (operation as ChangeOperation<Type>).to;
+    return operation.to;
+  }
+
+  // Initialize the resource.
+  protected initialize() {
+    if (this.resourceName.type === '') {
+      this.resourceName.type = this.type;
+    }
+    if (this.resourceName.prefix === '') {
+      this.resourceName.prefix = this.project.projectPrefix;
+    }
+    if (this.type) {
+      this.moduleResource =
+        this.resourceName.prefix !== this.project.projectPrefix;
+      this.resourceFolder = this.moduleResource
+        ? join(
+            this.project.paths.modulesFolder,
+            this.resourceName.prefix,
+            this.resourceName.type,
+          )
+        : this.project.paths.resourcePath(this.type);
+      this.fileName = resourceNameToPath(this.project, this.resourceName);
+    }
+    // Read from cache, if entry exists...
+    if (this.cache.has(resourceNameToString(this.resourceName))) {
+      this.content = this.cache.get(
+        resourceNameToString(this.resourceName),
+      ) as unknown as T;
+      return;
+    }
+    //... otherwise read from disk and add to cache
+    try {
+      this.content = readJsonFileSync(this.fileName);
+      this.toCache();
+    } catch {
+      // do nothing, it is possible that file has not been created yet.
+      this.logger.info(
+        `Initializing resource '${resourceNameToString(this.resourceName)}' failed: failed to read file '${this.fileName}'`,
+      );
+    }
+  }
+
+  // Called after inherited class has finished 'update' operation.
+  protected async postUpdate<Type, K extends string>(
+    content: T,
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    function toValue(op: Operation<Type>) {
+      if (op.name === 'rank') return op.newIndex;
+      if (op.name === 'add') return JSON.stringify(op.target);
+      if (op.name === 'remove') return JSON.stringify(op.target);
+      if (op.name === 'change') return JSON.stringify(op.to);
+    }
+
+    // Check that new name is valid.
+    if (op.name === 'change' && updateKey.key === 'name') {
+      const newName = resourceName(
+        (op as ChangeOperation<string>).to as string,
+      );
+      content.name = await this.validName(newName);
+    }
+
+    // Once changes have been made; validate the content.
+    try {
+      await this.validate(content);
+    } catch (error) {
+      if (error instanceof Error) {
+        const errorValue = typeof op === 'object' ? toValue(op) : op;
+        throw new Error(
+          `Cannot ${op.name} '${updateKey.key}' --> '${errorValue}: ${error.message}'`,
+        );
+      }
+    }
+
+    this.content = content;
+    await this.write();
+  }
+
+  // Update resource; the base class makes some checks only.
+  protected async update<Type, K extends string>(
+    key: UpdateKey<K>,
+    _op: Operation<Type>,
+  ): Promise<void> {
+    const content = this.data;
+    if (!content) {
+      throw new Error(
+        `Resource '${resourceNameToString(this.resourceName)}' does not exist`,
+      );
+    }
+    if (this.moduleResource) {
+      throw new Error(`Cannot update module resources`);
+    }
+    if (key.key === '' || key === undefined) {
+      throw new Error(`Cannot update empty key`);
+    }
+  }
+
+  // Reads content from file to memory.
+  protected async read() {
+    this.content = await readJsonFile(this.fileName);
+  }
+
+  // Renames resource.
+  protected async rename(newName: ResourceName) {
+    if (this.moduleResource) {
+      throw new Error(`Cannot rename module resources`);
+    }
+    if (!pathExists(this.fileName)) {
+      throw new Error(
+        `Resource '${this.resourceName.identifier}' does not exist`,
+      );
+    }
+    if (newName.prefix !== this.project.projectPrefix) {
+      throw new Error('Can only rename project resources');
+    }
+    if (newName.type !== this.resourceName.type) {
+      throw new Error('Cannot change resource type');
+    }
+    const validator = await ResourceObject.getValidate();
+    validator.validResourceName(
+      this.resourceType(),
+      resourceNameToString(newName),
+      await this.project.projectPrefixes(),
+    );
+    const newFilename = join(
+      this.project.paths.resourcePath(newName.type as ResourceFolderType),
+      newName.identifier + '.json',
+    );
+    await rename(this.fileName, newFilename);
+
+    this.cache.delete(resourceNameToString(this.resourceName));
+    this.fileName = newFilename;
+    this.content.name = resourceNameToString(newName);
+    this.resourceName = newName;
+    this.toCache();
   }
 
   /**
@@ -284,4 +578,113 @@ export class ResourceObject extends AbstractResource {
       }),
     );
   }
+
+  // Check if there are references to the resource in the card content.
+  // @note that this needs to be async, since inherited classes need to async operations
+  protected async usage(cards?: Card[]): Promise<string[]> {
+    if (!pathExists(this.fileName)) {
+      throw new Error(
+        `Resource '${this.resourceName.identifier}' does not exist in the project`,
+      );
+    }
+    const cardArray = cards?.length ? cards : this.project.cards(undefined);
+
+    return cardArray
+      .filter((card) =>
+        card.content?.includes(resourceNameToString(this.resourceName)),
+      )
+      .map((card) => card.key);
+  }
+
+  protected async validName(newName: ResourceName) {
+    const validator = await ResourceObject.getValidate();
+    const validName = validator.validResourceName(
+      this.resourceType(),
+      resourceNameToString(newName),
+      await this.project.projectPrefixes(),
+    );
+    return validName;
+  }
+
+  // Write the content from memory to disk.
+  protected async write() {
+    if (this.moduleResource) {
+      throw new Error(`Cannot change module resources`);
+    }
+
+    // Create folder for resources and add correct .schema file.
+    await mkdir(this.resourceFolder, { recursive: true });
+    await writeJsonFile(
+      join(this.resourceFolder, '.schema'),
+      this.contentSchema,
+      {
+        flag: 'wx',
+      },
+    );
+    // Check if "name" has changed. Changing "name" means renaming the file.
+    const nameInContent = resourceName(this.content.name).identifier + '.json';
+    const currentFileName = basename(this.fileName);
+
+    if (nameInContent !== currentFileName) {
+      const newFileName = join(this.resourceFolder, nameInContent);
+      await rename(this.fileName, newFileName);
+      this.fileName = newFileName;
+    }
+
+    await writeJsonFile(this.fileName, this.content);
+    this.toCache();
+  }
+
+  /**
+   * Returns memory resident data as JSON.
+   * This is basically same as 'show' but doesn't do any checks; just returns the current content.
+   * @returns metadata content or undefined if resource does not exist.
+   */
+  public get data() {
+    return this.content.name !== '' ? this.content : undefined;
+  }
+
+  /**
+   * Deletes the file and removes the resource from project.
+   * @throws if resource is a module resource or does not exist or is used by other resources.
+   */
+  public async delete() {
+    if (this.moduleResource) {
+      throw new Error(
+        `Cannot delete resource ${resourceNameToString(this.resourceName)}: It is a module resource`,
+      );
+    }
+    if (!this.fileName.endsWith('.json')) {
+      this.fileName += '.json';
+    }
+    if (!pathExists(this.fileName)) {
+      throw new Error(
+        `Resource '${this.resourceName.identifier}' does not exist in the project`,
+      );
+    }
+    const usedIn = await this.usage();
+    if (usedIn.length > 0) {
+      throw new Error(
+        `Cannot delete resource ${resourceNameToString(this.resourceName)}. It is used by: ${usedIn.join(', ')}`,
+      );
+    }
+    await deleteFile(this.fileName);
+    this.project.removeResource(this.resourceObjectToResource());
+    this.fileName = '';
+  }
+
+  /**
+   * Validates the content of the resource.
+   * @param content Content to be validated.
+   */
+  public async validate(content?: object) {
+    const validator = await ResourceObject.getValidate();
+    const invalidJson = validator.validateJson(
+      content ? content : this.content,
+      this.contentSchemaId,
+    );
+    if (invalidJson.length) {
+      throw new Error(`Invalid content JSON: ${invalidJson}`);
+    }
+  }
 }

package/src/resources/template-resource.ts

@@ -11,7 +11,7 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { basename, dirname, join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { mkdir } from 'node:fs/promises';
 
 import type {
@@ -29,6 +29,7 @@ import {
 import type {
   TemplateConfiguration,
   TemplateMetadata,
+  UpdateKey,
 } from '../interfaces/resource-interfaces.js';
 import { Template } from '../containers/template.js';
 import { writeJsonFile } from '../utils/json.js';
@@ -36,7 +37,7 @@ import { writeJsonFile } from '../utils/json.js';
 /**
  * Template resource class.
  */
-export class TemplateResource extends FolderResource {
+export class TemplateResource extends FolderResource<TemplateMetadata, never> {
   private cardContainer: Template;
   private cardsFolder = '';
   private cardsSchema = super.contentSchemaContent('cardBaseSchema');
@@ -47,12 +48,11 @@ export class TemplateResource extends FolderResource {
     this.contentSchemaId = 'templateSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
 
-    this.initialize();
     this.cardsFolder = join(this.internalFolder, 'c');
 
     // Each template resource contains a template card container (with template cards).
     this.cardContainer = new Template(this.project, {
-      name: basename(this.fileName),
+      name: resourceNameToString(this.resourceName),
       path: dirname(this.fileName),
     });
   }
@@ -86,13 +86,6 @@ export class TemplateResource extends FolderResource {
     return super.create(newContent);
   }
 
-  /**
-   * Returns content data.
-   */
-  public get data(): TemplateMetadata {
-    return super.data as TemplateMetadata;
-  }
-
   /**
    * Deletes file and folder that this resource is based on.
    */
@@ -115,7 +108,7 @@ export class TemplateResource extends FolderResource {
    * @returns template metadata.
    */
   public async show(): Promise<TemplateConfiguration> {
-    const templateMetadata = (await super.show()) as TemplateMetadata;
+    const templateMetadata = await super.show();
     const container = this.templateObject();
 
     return {
@@ -124,7 +117,7 @@ export class TemplateResource extends FolderResource {
       displayName: templateMetadata.displayName,
       description: templateMetadata.description,
       path: this.fileName,
-      numberOfCards: (await container.listCards()).length,
+      numberOfCards: container.listCards().length,
     };
   }
 
@@ -138,20 +131,24 @@ export class TemplateResource extends FolderResource {
 
   /**
    * Updates template resource.
-   * @param key Key to modify
+   * @param updateKey Key to modify
    * @param op Operation to perform on 'key'
    * @throws if key is unknown.
    */
-  public async update<Type>(key: string, op: Operation<Type>) {
+  public async update<Type, K extends string>(
+    updateKey: UpdateKey<K>,
+    op: Operation<Type>,
+  ) {
+    const { key } = updateKey;
     const nameChange = key === 'name';
     const existingName = this.content.name;
 
     // Only call super.update for keys that base class supports
     if (key === 'name' || key === 'displayName' || key === 'description') {
-      await super.update(key, op);
+      await super.update(updateKey, op);
     }
 
-    const content = structuredClone(this.content) as TemplateMetadata;
+    const content = structuredClone(this.content);
 
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
@@ -165,7 +162,7 @@ export class TemplateResource extends FolderResource {
       throw new Error(`Unknown property '${key}' for Template`);
     }
 
-    await super.postUpdate(content, key, op);
+    await super.postUpdate(content, updateKey, op);
 
     // Renaming this template causes that references to its name must be updated.
     if (nameChange) {
@@ -181,7 +178,7 @@ export class TemplateResource 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(),
@@ -189,16 +186,6 @@ export class TemplateResource extends FolderResource {
     return [...relevantCards.sort(sortCards), ...calculations];
   }
 
-  /**
-   * Validates template.
-   * @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 template's cards folder.
    */