@cyberismo/data-handler 0.0.14 → 0.0.16

package/src/project-settings.ts

@@ -12,6 +12,7 @@
 */
 
 import { writeJsonFile as atomicWrite } from 'write-json-file';
+import { writeFileSync } from 'node:fs';
 
 import { resolve } from 'node:path';
 import { URL } from 'node:url';
@@ -21,47 +22,51 @@ import type {
   ModuleSetting,
   ProjectSettings,
 } from './interfaces/project-interfaces.js';
+import { formatJson } from './utils/json.js';
+import { getChildLogger } from './utils/log-utils.js';
 import { readJsonFileSync } from './utils/json.js';
-import { Validate } from './commands/index.js';
+import { Validate } from './commands/validate.js';
+import { SCHEMA_VERSION } from '@cyberismo/assets';
 
 /**
  * Represents Project's cardsConfig.json file.
  */
 export class ProjectConfiguration implements ProjectSettings {
-  private static instance: ProjectConfiguration;
-
+  schemaVersion?: number;
   name: string;
   cardKeyPrefix: string;
   modules: ModuleSetting[];
   hubs: HubSetting[];
+  private logger = getChildLogger({ module: 'Project' });
   private settingPath: string;
+  private autoSave: boolean = false;
 
-  constructor(path: string) {
+  constructor(path: string, autoSave: boolean = true) {
     this.name = '';
     this.settingPath = path;
     this.cardKeyPrefix = '';
     this.modules = [];
     this.hubs = [];
+    this.autoSave = autoSave;
     this.readSettings();
+    this.ensureSchemaVersionAndSave();
   }
 
-  // Persists configuration file to disk.
-  public async save() {
-    if (this.cardKeyPrefix === '') {
-      throw new Error('wrong configuration');
-    }
-    try {
-      await atomicWrite(this.settingPath, this.toJSON(), { indent: 4 });
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(error.message);
+  // Ensures that schemaVersion is set in the project configuration.
+  // If missing, sets it to the current SCHEMA_VERSION and marks for auto-save.
+  private ensureSchemaVersionAndSave() {
+    if (this.schemaVersion === undefined) {
+      this.schemaVersion = SCHEMA_VERSION;
+      // Auto-saves the configuration, if schema version was updated.
+      if (this.autoSave) {
+        this.saveSync();
       }
     }
   }
 
   // Sets configuration values from file.
   private readSettings() {
-    const settings = readJsonFileSync(this.settingPath) as ProjectConfiguration;
+    const settings = readJsonFileSync(this.settingPath);
     if (!settings) {
       throw new Error(`File at '${this.settingPath}' is not a valid JSON file`);
     }
@@ -71,6 +76,7 @@ export class ProjectConfiguration implements ProjectSettings {
       Object.prototype.hasOwnProperty.call(settings, 'name');
 
     if (valid) {
+      this.schemaVersion = settings.schemaVersion;
       this.cardKeyPrefix = settings.cardKeyPrefix;
       this.name = settings.name;
       this.modules = settings.modules || [];
@@ -80,9 +86,24 @@ export class ProjectConfiguration implements ProjectSettings {
     }
   }
 
+  // Synchronously persists configuration file to disk.
+  private saveSync() {
+    if (this.cardKeyPrefix === '') {
+      throw new Error('wrong configuration');
+    }
+    try {
+      writeFileSync(this.settingPath, formatJson(this.toJSON()), 'utf-8');
+    } catch (error) {
+      if (error instanceof Error) {
+        this.logger.error({ error }, 'Cannot write project configuration');
+      }
+    }
+  }
+
   // Return the configuration as object
   private toJSON(): ProjectSettings {
     return {
+      schemaVersion: this.schemaVersion,
       cardKeyPrefix: this.cardKeyPrefix,
       name: this.name,
       modules: this.modules,
@@ -152,6 +173,39 @@ export class ProjectConfiguration implements ProjectSettings {
     return this.save();
   }
 
+  /**
+   * Checks schema version compatibility.
+   * @returns Compatibility state (true - compatible; false - not) and optional message related to it.
+   */
+  public checkSchemaVersion(): { isCompatible: boolean; message: string } {
+    if (this.schemaVersion === undefined) {
+      return {
+        isCompatible: true,
+        message: '',
+      };
+    }
+
+    if (this.schemaVersion < SCHEMA_VERSION) {
+      return {
+        isCompatible: false,
+        message: `Schema version mismatch: Project schema version (${this.schemaVersion}) is older than the application schema version (${SCHEMA_VERSION}). A migration is needed.`,
+      };
+    }
+
+    if (this.schemaVersion > SCHEMA_VERSION) {
+      return {
+        isCompatible: false,
+        message: `Schema version mismatch: Project schema version (${this.schemaVersion}) is newer than the application schema version (${SCHEMA_VERSION}). Please update the application.`,
+      };
+    }
+
+    // Schema versions are equal
+    return {
+      isCompatible: true,
+      message: '',
+    };
+  }
+
   /**
    * Removes a hub.
    * @param hubName Name of the hub to remove.
@@ -169,6 +223,7 @@ export class ProjectConfiguration implements ProjectSettings {
   /**
    * Removes module from imported modules property.
    * @param moduleName Name of the module to remove.
+   * @throws If Module name is empty, or not imported to the project.
    */
   public async removeModule(moduleName: string) {
     if (!moduleName) {
@@ -182,6 +237,20 @@ export class ProjectConfiguration implements ProjectSettings {
     return this.save();
   }
 
+  // Persists configuration file to disk.
+  public async save() {
+    if (this.cardKeyPrefix === '') {
+      throw new Error('wrong configuration');
+    }
+    try {
+      await atomicWrite(this.settingPath, this.toJSON(), { indent: 4 });
+    } catch (error) {
+      if (error instanceof Error) {
+        this.logger.error({ error }, 'Could not write project configuration');
+      }
+    }
+  }
+
   /**
    * Changes project prefix.
    * @param newPrefix New prefix to use in the project

package/src/resources/calculation-resource.ts

@@ -14,39 +14,31 @@
 
 import { join } from 'node:path';
 
-import {
-  DefaultContent,
-  FolderResource,
-  resourceNameToString,
-  sortCards,
-} from './folder-resource.js';
+import { CONTENT_FILES } from '../interfaces/folder-content-interfaces.js';
+import { DefaultContent } from '../resources/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 type {
-  Calculation,
-  CalculationMetadata,
-  CalculationUpdateKey,
-} from '../interfaces/resource-interfaces.js';
 import type { CalculationContent } from '../interfaces/folder-content-interfaces.js';
-import type {
-  Card,
-  Operation,
-  Project,
-  ResourceName,
-} from './file-resource.js';
+import type { CalculationMetadata } from '../interfaces/resource-interfaces.js';
+import type { Card } from '../interfaces/project-interfaces.js';
+import type { Project } from '../containers/project.js';
+import type { ResourceName } from '../utils/resource-utils.js';
 
 /**
  * Calculation resource class.
  */
-export class CalculationResource extends FolderResource {
-  private calculationsFile = 'calculation.lp';
+export class CalculationResource extends FolderResource<
+  CalculationMetadata,
+  CalculationContent
+> {
   constructor(project: Project, name: ResourceName) {
     super(project, name, 'calculations');
 
     this.contentSchemaId = 'calculationSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
-
-    this.initialize();
   }
 
   // When resource name changes
@@ -69,30 +61,15 @@ export class CalculationResource extends FolderResource {
     }
     await super.create(newContent);
 
-    const calculationsFile = join(this.internalFolder, this.calculationsFile);
-    await writeFileSafe(
-      calculationsFile,
-      `% add your calculations here for '${this.resourceName.identifier}'`,
-      {
-        flag: 'wx',
-      },
-    );
-  }
-
-  /**
-   * Returns content data.
-   */
-  public get data(): CalculationMetadata {
-    return super.data as CalculationMetadata;
-  }
+    const calculationContent = `% add your calculations here for '${this.resourceName.identifier}'`;
+    const calculationFile = CONTENT_FILES.calculation;
+    const calculationsFile = join(this.internalFolder, calculationFile);
+    await writeFileSafe(calculationsFile, calculationContent, {
+      flag: 'wx',
+    });
 
-  /**
-   * Deletes files from disk and clears out the memory resident object.
-   */
-  public async delete() {
-    await super.delete();
+    await this.loadContentFiles();
   }
-
   /**
    * Renames resource metadata file and renames memory resident object 'name'.
    * @param newName New name for the resource.
@@ -103,45 +80,6 @@ export class CalculationResource extends FolderResource {
     return this.onNameChange(existingName);
   }
 
-  /**
-   * Shows metadata of the resource.
-   * @returns calculation metadata.
-   */
-  public async show(): Promise<Calculation> {
-    const baseData = (await super.show()) as CalculationMetadata;
-    const fileContents = await super.contentData();
-    const content: CalculationContent = {
-      calculation: fileContents.calculation as string,
-    };
-    return {
-      ...baseData,
-      content: content,
-    };
-  }
-
-  /**
-   * Updates calculation resource.
-   * @template Type The type of the operation being operated on for the given key.
-   * @param key Key to modify
-   * @param op Operation to perform on 'key'
-   * @example
-   * // Update the description
-   *    await calculation.update('description', { name: 'change', to: 'New description' });
-   *    await calculation.update({ key: 'content', subKey: 'calculation' }, { name: 'change', to: 'new content' });
-   */
-  public async update<Type>(key: CalculationUpdateKey, op: Operation<Type>) {
-    if (
-      typeof key === 'object' &&
-      key.key === 'content' &&
-      key.subKey === 'calculation'
-    ) {
-      const calculationContent = super.handleScalar(op) as string;
-      await this.updateFile(this.calculationsFile, calculationContent);
-      return;
-    }
-    await super.update(key, op);
-  }
-
   /**
    * List where calculation resource is used in cards, or other calculation resources.
    * Always returns card key references first, then calculation references.
@@ -150,7 +88,7 @@ export class CalculationResource 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 [cardContentReferences, calculations] = await Promise.all([
       super.usage(allCards),
@@ -160,12 +98,4 @@ export class CalculationResource extends FolderResource {
     const cardReferences = cardContentReferences.sort(sortCards);
     return [...new Set([...cardReferences, ...calculations])];
   }
-
-  /**
-   * Validates the resource. If object is invalid, throws.
-   * @param content Content to validate
-   */
-  public async validate(content?: object) {
-    return super.validate(content);
-  }
 }

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

@@ -12,47 +12,44 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+import { DefaultContent } from './create-defaults.js';
+import { FileResource } from './file-resource.js';
+import { resourceName, resourceNameToString } from '../utils/resource-utils.js';
+import { ResourcesFrom } from '../containers/project.js';
+import { sortCards } from '../utils/card-utils.js';
+import { Validate } from '../commands/validate.js';
+
+import type {
+  AddOperation,
+  ChangeOperation,
+  Operation,
+  RemoveOperation,
+} from './resource-object.js';
+import type { Card } from '../interfaces/project-interfaces.js';
 import type {
   CardType,
   CustomField,
   LinkType,
-  Workflow,
+  UpdateKey,
 } from '../interfaces/resource-interfaces.js';
-import { FieldTypeResource } from './field-type-resource.js';
-import {
-  type AddOperation,
-  type Card,
-  type ChangeOperation,
-  DefaultContent,
-  FileResource,
-  type Operation,
-  type Project,
-  type RemoveOperation,
-  ResourcesFrom,
-  type ResourceName,
-  resourceName,
-  resourceNameToString,
-  sortCards,
-} from './file-resource.js';
-import { LinkTypeResource } from './link-type-resource.js';
-import { Validate } from '../commands/index.js';
+import type { Project } from '../containers/project.js';
+import type { ResourceName } from '../utils/resource-utils.js';
 
 /**
  * Card type resource class.
  */
-export class CardTypeResource extends FileResource {
+export class CardTypeResource extends FileResource<CardType> {
   constructor(project: Project, name: ResourceName) {
     super(project, name, 'cardTypes');
 
     this.contentSchemaId = 'cardTypeSchema';
     this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
 
-    this.initialize();
     this.setContainerValues();
   }
 
   // Returns cards that have this card type.
-  private async cardsWithCardType(cards: Card[]): Promise<string[]> {
+  private cardsWithCardType(cards: Card[]): string[] {
     const resourceName = resourceNameToString(this.resourceName);
     return cards
       .filter((card) => card.metadata?.cardType === resourceName)
@@ -62,7 +59,7 @@ export class CardTypeResource extends FileResource {
   // Checks if field type exists in the project.
   private async fieldTypeExists(field: Partial<CustomField>) {
     return field && field.name
-      ? this.project.resourceExists('fieldTypes', field.name)
+      ? this.project.resources.exists(field.name)
       : false;
   }
 
@@ -72,13 +69,7 @@ export class CardTypeResource extends FileResource {
     if (op && op.name === 'rank') return;
 
     // Collect both project cards and template cards.
-    const cards = await this.collectCards(
-      {
-        metadata: true,
-        content: true,
-      },
-      this.content.name,
-    );
+    const cards = await this.collectCards(this.content.name);
 
     if (op && op.name === 'change') {
       const from = (op as ChangeOperation<string>).target;
@@ -113,8 +104,8 @@ export class CardTypeResource extends FileResource {
 
   // When resource name changes.
   private async handleNameChange(existingName: string) {
-    const current = this.content as CardType;
-    const prefixes = await this.project.projectPrefixes();
+    const current = this.content;
+    const prefixes = this.project.projectPrefixes();
     if (current.customFields) {
       current.customFields.map(
         (field) =>
@@ -160,20 +151,14 @@ export class CardTypeResource extends FileResource {
     op: ChangeOperation<Type>,
   ) {
     await this.verifyStateMapping(stateMapping, op);
-    const cards = await this.collectCards(
-      {
-        metadata: true,
-        content: true,
-      },
-      this.content.name,
-    );
+    const cards = await this.collectCards(this.content.name);
 
     const unmappedStates: string[] = [];
 
     // Update each card's workflowState if it has a mapping
     const updatePromises = cards.map(async (card) => {
       if (card.metadata && card.metadata.workflowState) {
-        const currentState = card.metadata.workflowState as string;
+        const currentState = card.metadata.workflowState;
         const newState = stateMapping[currentState];
 
         if (newState && newState !== currentState) {
@@ -198,8 +183,10 @@ export class CardTypeResource extends FileResource {
   }
 
   // Checks if field type exists in this card type.
-  private async hasFieldType(field: Partial<CustomField>): Promise<boolean> {
-    return this.data.customFields.some((item) => item.name === field.name);
+  private hasFieldType(field: Partial<CustomField>): boolean {
+    return (
+      this.data?.customFields.some((item) => item.name === field.name) || false
+    );
   }
 
   // Remove value from array.
@@ -212,24 +199,25 @@ export class CardTypeResource extends FileResource {
   }
 
   // Return link types that use this card type.
-  private async relevantLinkTypes(): Promise<string[]> {
+  private relevantLinkTypes(): string[] {
     const resourceName = resourceNameToString(this.resourceName);
-    const allLinkTypes = await this.project.linkTypes(ResourcesFrom.all);
+    const allLinkTypes = this.project.resources.linkTypes();
+    const references: string[] = [];
 
-    const linkTypeNames = await Promise.all(
-      allLinkTypes.map(async (linkType) => {
-        const metadata = await this.project.resource<LinkType>(linkType.name);
-        if (!metadata) return null;
+    for (const linkType of allLinkTypes) {
+      const metadata = linkType.data;
+      if (!metadata) continue;
 
-        const isRelevant =
-          metadata.destinationCardTypes.includes(resourceName) ||
-          metadata.sourceCardTypes.includes(resourceName);
+      const isRelevant =
+        metadata.destinationCardTypes.includes(resourceName) ||
+        metadata.sourceCardTypes.includes(resourceName);
 
-        return isRelevant ? linkType.name : null;
-      }),
-    );
+      if (isRelevant) {
+        references.push(metadata.name);
+      }
+    }
 
-    return linkTypeNames.filter((name): name is string => name !== null);
+    return references;
   }
 
   // If value from 'customFields' is removed, remove it also from 'optionallyVisible' and 'alwaysVisible' arrays.
@@ -251,7 +239,7 @@ export class CardTypeResource extends FileResource {
 
   // Sets content container values to be either '[]' or with proper values.
   private setContainerValues() {
-    const content = this.content as CardType;
+    const content = this.content;
     if (content.customFields) {
       for (const item of content.customFields) {
         // Set "isCalculated" if it is missing; default = false
@@ -260,9 +248,9 @@ export class CardTypeResource extends FileResource {
         }
         // Fetch "displayName" from field type if it is missing.
         if (item.name && item.displayName === undefined) {
-          const fieldType = new FieldTypeResource(
-            this.project,
-            resourceName(item.name),
+          const fieldType = this.project.resources.byType(
+            item.name,
+            'fieldTypes',
           );
           const fieldTypeContent = fieldType.data;
           if (fieldTypeContent) {
@@ -289,14 +277,9 @@ export class CardTypeResource extends FileResource {
 
   // Updates dependent link types.
   private async updateLinkTypes(oldName: string): Promise<void> {
-    const linkTypes = await this.project.linkTypes(ResourcesFrom.localOnly);
-
-    const updatePromises = linkTypes.map(async (linkType) => {
-      const object = new LinkTypeResource(
-        this.project,
-        resourceName(linkType.name),
-      );
+    const linkTypes = this.project.resources.linkTypes(ResourcesFrom.localOnly);
 
+    const updatePromises = linkTypes.map(async (object) => {
       const data = object.data;
       const updates: Promise<void>[] = [];
 
@@ -311,7 +294,7 @@ export class CardTypeResource extends FileResource {
             target: oldName,
             to: this.content.name,
           } as ChangeOperation<string>;
-          updates.push(object.update(field, op));
+          updates.push(object.update({ key: field }, op));
         }
       }
 
@@ -353,7 +336,7 @@ export class CardTypeResource extends FileResource {
     }
     // Check that field type is defined in card type.
     if (key === 'alwaysVisibleFields' || key === 'optionallyVisibleFields') {
-      const hasField = await this.hasFieldType(field);
+      const hasField = this.hasFieldType(field);
       if (!hasField) {
         throw new Error(
           `Field type '${field.name}' is not defined in card type '${this.content.name}'`,
@@ -370,15 +353,19 @@ export class CardTypeResource extends FileResource {
     op: ChangeOperation<Type>,
   ) {
     const currentWorkflowName = op.target as string;
-    const currentWorkflow =
-      await this.project.resource<Workflow>(currentWorkflowName);
+    const currentWorkflow = this.project.resources
+      .byType(currentWorkflowName, 'workflows')
+      .show();
     if (!currentWorkflow) {
       throw new Error(
         `Workflow '${currentWorkflowName}' does not exist in the project`,
       );
     }
 
-    const newWorkflow = await this.project.resource<Workflow>(op.to as string);
+    const newWorkflow = this.project.resources
+      .byType(op.to as string, 'workflows')
+      .show();
+
     if (!newWorkflow) {
       throw new Error(`Workflow '${op.to}' does not exist in the project`);
     }
@@ -416,6 +403,7 @@ export class CardTypeResource extends FileResource {
   /**
    * Creates a new card type object. Base class writes the object to disk automatically.
    * @param workflowName Workflow name that this card type uses.
+   * @throws when workflow is empty, or does not exist in the project.
    */
   public async createCardType(workflowName: string) {
     if (!workflowName) {
@@ -423,12 +411,14 @@ export class CardTypeResource extends FileResource {
         `Cannot create cardType without providing workflow for it`,
       );
     }
-    const validWorkflowName = await Validate.getInstance().validResourceName(
+    const validWorkflowName = Validate.getInstance().validResourceName(
       'workflows',
       resourceNameToString(resourceName(workflowName)),
-      await this.project.projectPrefixes(),
+      this.project.projectPrefixes(),
     );
-    const workflow = await this.project.resource<Workflow>(workflowName);
+    const workflow = this.project.resources
+      .byType(workflowName, 'workflows')
+      .show();
     if (!workflow) {
       throw new Error(
         `Workflow '${workflowName}' does not exist in the project`,
@@ -441,20 +431,6 @@ export class CardTypeResource extends FileResource {
     return super.create(content);
   }
 
-  /**
-   * Returns content data.
-   */
-  public get data(): CardType {
-    return super.data as CardType;
-  }
-
-  /**
-   * Deletes file(s) from disk and clears out the memory resident object.
-   */
-  public async delete() {
-    return super.delete();
-  }
-
   /**
    * Renames resource metadata file and renames memory resident object 'name'.
    * @param newName New name for the resource.
@@ -465,26 +441,22 @@ export class CardTypeResource extends FileResource {
     return this.handleNameChange(existingName);
   }
 
-  /**
-   * Shows metadata of the resource.
-   * @returns card type metadata.
-   */
-  public async show(): Promise<CardType> {
-    return super.show() as Promise<CardType>;
-  }
-
   /**
    * Updates card type resource.
-   * @param key Key to modify
+   * @param updateKey Key to modify
    * @param op Operation to perform on 'key'
    */
-  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 customFieldsChange = key === 'customFields';
     const existingName = this.content.name;
-    await super.update(key, op);
+    await super.update(updateKey, op);
 
-    const content = structuredClone(this.content) as CardType;
+    const content = structuredClone(this.content);
     if (key === 'name') {
       content.name = super.handleScalar(op) as string;
     } else if (key === 'alwaysVisibleFields') {
@@ -525,7 +497,7 @@ export class CardTypeResource extends FileResource {
     } else {
       throw new Error(`Unknown property '${key}' for CardType`);
     }
-    await super.postUpdate(content, key, op);
+    await super.postUpdate(content, updateKey, op);
 
     // Renaming this card type causes that references to its name must be updated.
     if (nameChange) {
@@ -544,7 +516,7 @@ export class CardTypeResource extends FileResource {
    * @returns array of card keys, resource names 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 [
       cardsWithCardType,
       cardContentReferences,
@@ -566,11 +538,4 @@ export class CardTypeResource extends FileResource {
       ...new Set([...cardReferences, ...relevantLinkTypes, ...calculations]),
     ];
   }
-
-  /**
-   * Validates the resource. If object is invalid, throws.
-   */
-  public async validate(content?: object) {
-    return super.validate(content);
-  }
 }