@cyberismo/data-handler 0.0.15 → 0.0.17

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,40 +22,44 @@ 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();
       }
     }
   }
@@ -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
@@ -196,4 +265,17 @@ export class ProjectConfiguration implements ProjectSettings {
       `Prefix '${newPrefix}' is not valid prefix. Prefix should be in lowercase and contain letters from a to z (max length 10).`,
     );
   }
+
+  /**
+   * Changes project name.
+   * @param newName New project name
+   */
+  public async setProjectName(newName: string) {
+    const isValid = Validate.isValidProjectName(newName);
+    if (isValid) {
+      this.name = newName;
+      return this.save();
+    }
+    throw new Error(`Project name '${newName}' is not valid.`);
+  }
 }

package/src/resources/calculation-resource.ts

@@ -14,17 +14,18 @@
 
 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 CalculationMetadata } from '../interfaces/resource-interfaces.js';
 import type { CalculationContent } from '../interfaces/folder-content-interfaces.js';
-import type { Card, 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.
@@ -33,7 +34,6 @@ export class CalculationResource extends FolderResource<
   CalculationMetadata,
   CalculationContent
 > {
-  private calculationsFile = 'calculation.lp';
   constructor(project: Project, name: ResourceName) {
     super(project, name, 'calculations');
 
@@ -61,14 +61,14 @@ 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',
-      },
-    );
+    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',
+    });
+
+    await this.loadContentFiles();
   }
   /**
    * Renames resource metadata file and renames memory resident object 'name'.
@@ -88,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),

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

@@ -12,31 +12,28 @@
   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,
   UpdateKey,
-  Workflow,
 } 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.
@@ -62,7 +59,7 @@ export class CardTypeResource extends FileResource<CardType> {
   // 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;
   }
 
@@ -108,7 +105,7 @@ export class CardTypeResource extends FileResource<CardType> {
   // When resource name changes.
   private async handleNameChange(existingName: string) {
     const current = this.content;
-    const prefixes = await this.project.projectPrefixes();
+    const prefixes = this.project.projectPrefixes();
     if (current.customFields) {
       current.customFields.map(
         (field) =>
@@ -202,24 +199,25 @@ export class CardTypeResource extends FileResource<CardType> {
   }
 
   // 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.
@@ -250,9 +248,9 @@ export class CardTypeResource extends FileResource<CardType> {
         }
         // 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) {
@@ -279,14 +277,9 @@ export class CardTypeResource extends FileResource<CardType> {
 
   // 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>[] = [];
 
@@ -343,7 +336,7 @@ export class CardTypeResource extends FileResource<CardType> {
     }
     // 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}'`,
@@ -360,15 +353,19 @@ export class CardTypeResource extends FileResource<CardType> {
     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`);
     }
@@ -406,6 +403,7 @@ export class CardTypeResource extends FileResource<CardType> {
   /**
    * 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) {
@@ -416,9 +414,11 @@ export class CardTypeResource extends FileResource<CardType> {
     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`,

package/src/resources/create-defaults.ts

@@ -189,7 +189,8 @@ export abstract class DefaultContent {
   }
 
   /**
-   * Default template content
+   * Default template content.
+   * @param templateName Template name
    * @returns Default template content
    */
   public static template(templateName: string): TemplateMetadata {
@@ -201,7 +202,7 @@ export abstract class DefaultContent {
 
   /**
    * Default content for workflow JSON values.
-   * @param {string} workflowName workflow name
+   * @param workflowName workflow name
    * @returns Default content for workflow JSON values.
    */
   public static workflow(workflowName: string): Workflow {

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

@@ -11,38 +11,33 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+import {
+  allowed,
+  fromDate,
+  fromNumber,
+  fromString,
+} from '../utils/value-utils.js';
+import { DefaultContent } from './create-defaults.js';
+import { FileResource } from './file-resource.js';
+import { resourceNameToString } from '../utils/resource-utils.js';
+import { sortCards } from '../utils/card-utils.js';
+
+import * as EmailValidator from 'email-validator';
+
 import type {
-  Card,
   ChangeOperation,
   Operation,
-  Project,
   RemoveOperation,
-  ResourceName,
-} from './file-resource.js';
-import {
-  DefaultContent,
-  FileResource,
-  ResourcesFrom,
-  resourceName,
-  resourceNameToString,
-  sortCards,
-} from './file-resource.js';
-
+} from './resource-object.js';
+import type { Card } from '../interfaces/project-interfaces.js';
 import type {
-  CardType,
   DataType,
   EnumDefinition,
   FieldType,
   UpdateKey,
 } from '../interfaces/resource-interfaces.js';
-import { CardTypeResource } from './card-type-resource.js';
-import {
-  allowed,
-  fromDate,
-  fromNumber,
-  fromString,
-} from '../utils/value-utils.js';
-import * as EmailValidator from 'email-validator';
+import type { Project } from '../containers/project.js';
+import type { ResourceName } from '../utils/resource-utils.js';
 
 const SHORT_TEXT_MAX_LENGTH = 80;
 
@@ -134,7 +129,7 @@ export class FieldTypeResource extends FileResource<FieldType> {
     }
 
     // First collect the cardTypes that need to be updated.
-    const cardTypes = await this.relevantCardTypes(ResourcesFrom.localOnly);
+    const cardTypes = this.relevantCardTypes();
     cardTypesThatUseThisFieldType.push(...cardTypes);
 
     // Then collect cards (both project and local template) that use those card types.
@@ -209,7 +204,7 @@ export class FieldTypeResource extends FileResource<FieldType> {
     if (!newValue) return;
 
     const removedValue = (op.target as EnumDefinition).enumValue;
-    const cardTypes = await this.relevantCardTypes(ResourcesFrom.localOnly);
+    const cardTypes = this.relevantCardTypes();
     const allCards = await Promise.all(
       cardTypes.map((cardType) => this.collectCards(cardType)),
     );
@@ -255,44 +250,35 @@ export class FieldTypeResource extends FileResource<FieldType> {
   }
 
   // Card types that use field type.
-  private async relevantCardTypes(from: ResourcesFrom): Promise<string[]> {
+  private relevantCardTypes(): string[] {
     const resourceName = resourceNameToString(this.resourceName);
-    const cardTypes = await this.project.cardTypes(from);
-
-    const references = await Promise.all(
-      cardTypes.map(async (cardType) => {
-        const metadata = await this.project.resource<CardType>(cardType.name);
-        return metadata?.customFields.some(
-          (field) => field.name === resourceName,
-        )
-          ? cardType.name
-          : '';
-      }),
-    );
-    // Remove empty values.
-    return references.filter(Boolean);
+    const cardTypes = this.project.resources.cardTypes();
+    const references = [];
+    for (const cardType of cardTypes) {
+      const found = cardType.data?.customFields.filter(
+        (field) => field.name === resourceName,
+      );
+      if (found && found.length > 0 && cardType.data)
+        references.push(cardType.data?.name);
+    }
+    return references;
   }
 
   // Update dependant card types
   private async updateCardTypes(oldName: string) {
-    const cardTypes = await this.project.cardTypes(ResourcesFrom.localOnly);
+    const cardTypes = this.project.resources.cardTypes();
     const op = {
       name: 'change',
       target: oldName,
       to: this.content.name,
     } as ChangeOperation<string>;
     for (const cardType of cardTypes) {
-      const object = new CardTypeResource(
-        this.project,
-        resourceName(cardType.name),
-      );
-      const data = object.data;
-      if (data) {
-        const found = data.customFields
-          ? data.customFields.find((item) => item.name === oldName)
+      if (cardType.data?.customFields) {
+        const found = cardType.data.customFields
+          ? cardType.data.customFields.find((item) => item.name === oldName)
           : undefined;
         if (found) {
-          await object.update({ key: 'customFields' }, op);
+          await cardType.update({ key: 'customFields' }, op);
         }
       }
     }
@@ -474,12 +460,12 @@ export class FieldTypeResource extends FileResource<FieldType> {
   public async usage(cards?: Card[]): Promise<string[]> {
     const allCards = cards ?? super.cards();
 
-    const [cardContentReferences, relevantLinkTypes, calculations] =
-      await Promise.all([
-        super.usage(allCards),
-        this.relevantCardTypes(ResourcesFrom.all),
-        super.calculations(),
-      ]);
+    const relevantLinkTypes = this.relevantCardTypes();
+
+    const [cardContentReferences, calculations] = await Promise.all([
+      super.usage(allCards),
+      super.calculations(),
+    ]);
 
     const cardReferences = [
       ...this.cardsWithFieldType(allCards),

package/src/resources/file-resource.ts

@@ -11,43 +11,18 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+import { resourceName } from '../utils/resource-utils.js';
+import { ResourceObject } from './resource-object.js';
+import { ResourcesFrom } from '../containers/project.js';
+
 import type {
   Card,
   ResourceFolderType,
 } from '../interfaces/project-interfaces.js';
-import type { ShowReturnType } from './resource-object.js';
-import {
-  type AddOperation,
-  type ChangeOperation,
-  type Operation,
-  type RemoveOperation,
-  ResourceObject,
-} from './resource-object.js';
-import { DefaultContent } from './create-defaults.js';
-import { Project, ResourcesFrom } from '../containers/project.js';
+import type { Project } from '../containers/project.js';
 import type { ResourceBaseMetadata } from '../interfaces/resource-interfaces.js';
-import {
-  type ResourceName,
-  resourceName,
-  resourceNameToString,
-} from '../utils/resource-utils.js';
-import { sortCards } from '../utils/card-utils.js';
-import { Template } from '../containers/template.js';
-
-export {
-  type AddOperation,
-  type Card,
-  type ChangeOperation,
-  DefaultContent,
-  type Operation,
-  Project,
-  RemoveOperation,
-  ResourcesFrom,
-  resourceName,
-  type ResourceName,
-  resourceNameToString,
-  sortCards,
-};
+import type { ResourceName } from '../utils/resource-utils.js';
+import type { ShowReturnType } from './resource-object.js';
 
 /**
  * Base class for file based resources (card types, field types, link types, workflows, ...)
@@ -72,9 +47,9 @@ export abstract class FileResource<
       cardTypeName,
     );
     // ... and cards from each template that would be affected.
-    const templates = await this.project.templates(ResourcesFrom.localOnly);
+    const templates = this.project.resources.templates(ResourcesFrom.localOnly);
     const templateCards = templates.map((template) => {
-      const templateObject = new Template(this.project, template);
+      const templateObject = template.templateObject();
       return filteredCards(templateObject.cards(), cardTypeName);
     });
     // Return all affected cards
@@ -98,9 +73,8 @@ export abstract class FileResource<
   /**
    * Returns the resource metadata content.
    * @returns metadata content
-   * @throws if resource does not exist.
    */
-  public async show(): Promise<ShowReturnType<T>> {
+  public show(): ShowReturnType<T> {
     this.assertResourceExists();
     return this.content;
   }