@cyberismo/data-handler 0.0.2

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

@@ -0,0 +1,205 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  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 type {
+  Card,
+  Operation,
+  Project,
+  ResourceName,
+} from './folder-resource.js';
+import {
+  DefaultContent,
+  FolderResource,
+  resourceNameToString,
+  sortCards,
+} from './folder-resource.js';
+import type {
+  GraphModel,
+  GraphModelMetadata,
+} from '../interfaces/resource-interfaces.js';
+import { writeFileSafe } from '../utils/file-utils.js';
+
+/**
+ * Graph model resource class.
+ */
+export class GraphModelResource extends FolderResource {
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'graphModels');
+
+    this.contentSchemaId = 'graphModelSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+
+    this.initialize();
+  }
+
+  // When resource name changes.
+  private async handleNameChange(existingName: string) {
+    await Promise.all([
+      super.updateHandleBars(existingName, this.content.name, [
+        await this.calculationFile(),
+      ]),
+      super.updateCalculations(existingName, this.content.name),
+    ]);
+    // Finally, write updated content.
+    await this.write();
+  }
+
+  /**
+   * Sets new metadata into the graph model object graph model.
+   * @param newContent metadata content for the graph model.
+   * @throws if 'newContent' is not valid.
+   */
+  public async create(newContent?: GraphModelMetadata) {
+    if (!newContent) {
+      newContent = DefaultContent.graphModel(
+        resourceNameToString(this.resourceName),
+      );
+    } else {
+      await this.validate(newContent);
+    }
+
+    await super.create(newContent);
+
+    // Create the internal folder in 'create', instead of 'write'.
+    const calculationsFile = join(this.internalFolder, 'model.lp');
+    await writeFileSafe(
+      calculationsFile,
+      `% add your calculations here for '${this.resourceName.identifier}'`,
+      {
+        flag: 'wx',
+      },
+    );
+  }
+
+  /**
+   * Returns resource content.
+   */
+  public get data(): GraphModel {
+    return super.data as GraphModel;
+  }
+
+  /**
+   * Deletes file and folder that this resource is based on.
+   */
+  public async delete() {
+    return super.delete();
+  }
+
+  /**
+   * Returns calculation file that this graph model has.
+   * @returns calculation file name that this graph model has.
+   */
+  public async calculationFile(nameOnly: boolean = false): Promise<string> {
+    return (
+      await readdir(this.internalFolder, {
+        withFileTypes: true,
+        recursive: true,
+      })
+    )
+      .filter((dirent) => dirent.isFile() && extname(dirent.name) === '.lp')
+      .map((item) => (nameOnly ? item.name : join(item.parentPath, item.name)))
+      .at(0)!;
+  }
+
+  /**
+   * Renames the object and the file.
+   * @param newName New name for the resource.
+   */
+  public async rename(newName: ResourceName) {
+    const existingName = this.content.name;
+    await super.rename(newName);
+    return this.handleNameChange(existingName);
+  }
+
+  /**
+   * Shows metadata of the resource.
+   * @returns graph model metadata.
+   */
+  public async show(): Promise<GraphModel> {
+    const showOnlyFileName = true;
+    const baseData = (await super.show()) as GraphModelMetadata;
+    return {
+      ...baseData,
+      calculationFile: await this.calculationFile(showOnlyFileName),
+    };
+  }
+
+  /**
+   * Updates graph model resource.
+   * @param key Key to modify
+   * @param op Operation to perform on 'key'
+   * @throws if key is unknown.
+   */
+  public async update<Type>(key: string, op: Operation<Type>) {
+    const nameChange = key === 'name';
+    const existingName = this.content.name;
+
+    await super.update(key, op);
+
+    const content = { ...(this.content as GraphModel) };
+
+    if (key === 'name') {
+      content.name = super.handleScalar(op) as string;
+    } else if (key === 'displayName') {
+      content.displayName = super.handleScalar(op) as string;
+    } else if (key === 'description') {
+      content.description = super.handleScalar(op) as string;
+    } else if (key === 'category') {
+      content.category = super.handleScalar(op) as string;
+    }
+
+    await super.postUpdate(content, key, op);
+
+    // Renaming this graph model causes that references to its name must be updated.
+    if (nameChange) {
+      await this.handleNameChange(existingName);
+    }
+  }
+
+  /**
+   * List where this resource is used.
+   * Always returns card key references first, then calculation references.
+   *
+   * @param cards Optional. Check these cards for usage of this resource. If undefined, will check all cards.
+   * @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 [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

@@ -0,0 +1,199 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  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 type {
+  Card,
+  Operation,
+  Project,
+  ResourceName,
+} from './folder-resource.js';
+import {
+  DefaultContent,
+  FolderResource,
+  resourceNameToString,
+  sortCards,
+} from './folder-resource.js';
+import type {
+  GraphView,
+  GraphViewMetadata,
+} from '../interfaces/resource-interfaces.js';
+import { writeFileSafe } from '../utils/file-utils.js';
+
+/**
+ * Graph view resource class.
+ */
+export class GraphViewResource extends FolderResource {
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'graphViews');
+
+    this.contentSchemaId = 'graphViewSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+
+    this.initialize();
+  }
+
+  // When resource name changes.
+  private async handleNameChange(existingName: string) {
+    await Promise.all([
+      super.updateHandleBars(existingName, this.content.name, [
+        await this.handleBarFile(),
+      ]),
+      super.updateCalculations(existingName, this.content.name),
+    ]);
+    // Finally, write updated content.
+    await this.write();
+  }
+
+  /**
+   * Sets new metadata into the graph view object.
+   * @param newContent metadata content for the graph view.
+   * @throws if 'newContent' is not valid.
+   */
+  public async create(newContent?: GraphViewMetadata) {
+    if (!newContent) {
+      newContent = DefaultContent.graphView(
+        resourceNameToString(this.resourceName),
+      );
+    } else {
+      await this.validate(newContent);
+    }
+
+    await super.create(newContent);
+    const handleBarFile = join(this.internalFolder, 'view.lp.hbs');
+    await writeFileSafe(handleBarFile, '', {
+      flag: 'wx',
+    });
+  }
+
+  /**
+   * 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.
+   */
+  public async handleBarFile(nameOnly: boolean = false): Promise<string> {
+    return (
+      await readdir(this.internalFolder, {
+        withFileTypes: true,
+        recursive: true,
+      })
+    )
+      .filter((dirent) => dirent.isFile() && extname(dirent.name) === '.hbs')
+      .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.
+   */
+  public async rename(newName: ResourceName) {
+    const existingName = this.content.name;
+    await super.rename(newName);
+    return this.handleNameChange(existingName);
+  }
+
+  /**
+   * Shows metadata of the resource.
+   * @returns graph view metadata.
+   */
+  public async show(): Promise<GraphView> {
+    const showOnlyFileName = true;
+    const baseData = (await super.show()) as GraphViewMetadata;
+    return {
+      ...baseData,
+      handleBarFile: await this.handleBarFile(showOnlyFileName),
+    };
+  }
+
+  /**
+   * Updates graph view resource.
+   * @param key Key to modify
+   * @param op Operation to perform on 'key'
+   * @throws if key is unknown.
+   */
+  public async update<Type>(key: string, op: Operation<Type>) {
+    const nameChange = key === 'name';
+    const existingName = this.content.name;
+
+    await super.update(key, op);
+
+    const content = { ...(this.content as GraphView) };
+
+    if (key === 'name') {
+      content.name = super.handleScalar(op) as string;
+    } else if (key === 'displayName') {
+      content.displayName = super.handleScalar(op) as string;
+    } else if (key === 'description') {
+      content.description = super.handleScalar(op) as string;
+    } else if (key === 'category') {
+      content.category = super.handleScalar(op) as string;
+    }
+
+    await super.postUpdate(content, key, op);
+
+    // Renaming this graph view causes that references to its name must be updated.
+    if (nameChange) {
+      await this.handleNameChange(existingName);
+    }
+  }
+
+  /**
+   * List where this resource is used.
+   * Always returns card key references first, then calculation references.
+   *
+   * @param cards Optional. Check these cards for usage of this resource. If undefined, will check all cards.
+   * @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 [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();
+  }
+}

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

@@ -0,0 +1,191 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import type {
+  Card,
+  Operation,
+  Project,
+  ResourceName,
+} from './file-resource.js';
+import {
+  DefaultContent,
+  FileResource,
+  resourceNameToString,
+  sortCards,
+} from './folder-resource.js';
+import type { LinkType } from '../interfaces/resource-interfaces.js';
+
+/**
+ * Link Type resource class.
+ */
+export class LinkTypeResource extends FileResource {
+  constructor(project: Project, name: ResourceName) {
+    super(project, name, 'linkTypes');
+
+    this.contentSchemaId = 'linkTypeSchema';
+    this.contentSchema = super.contentSchemaContent(this.contentSchemaId);
+
+    this.initialize();
+  }
+
+  // When resource name changes.
+  private async handleNameChange(existingName: string) {
+    const current = this.content as LinkType;
+    const prefixes = await this.project.projectPrefixes();
+    if (current.sourceCardTypes) {
+      current.sourceCardTypes = current.sourceCardTypes.map((item) =>
+        this.updatePrefixInResourceName(item, prefixes),
+      );
+    }
+    if (current.destinationCardTypes) {
+      current.destinationCardTypes = current.destinationCardTypes.map((item) =>
+        this.updatePrefixInResourceName(item, prefixes),
+      );
+    }
+    await Promise.all([
+      super.updateHandleBars(existingName, this.content.name),
+      super.updateCalculations(existingName, this.content.name),
+    ]);
+    // Finally, write updated content.
+    await this.write();
+  }
+
+  /**
+   * Creates a new link type object. Base class writes the object to disk automatically.
+   * @param newContent Content for the link type.
+   */
+  public async create(newContent?: LinkType) {
+    if (!newContent) {
+      newContent = DefaultContent.linkType(
+        resourceNameToString(this.resourceName),
+      );
+    } else {
+      await this.validate(newContent);
+    }
+    return super.create(newContent);
+  }
+
+  /**
+   * Returns content data.
+   */
+  public get data() {
+    return super.data as LinkType;
+  }
+
+  /**
+   * 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.
+   */
+  public async rename(newName: ResourceName) {
+    const existingName = this.content.name;
+    await super.rename(newName);
+    return this.handleNameChange(existingName);
+  }
+
+  /**
+   * Shows metadata of the resource.
+   * @returns link type metadata.
+   */
+  public async show(): Promise<LinkType> {
+    return super.show() as Promise<LinkType>;
+  }
+
+  /**
+   * Updates link type resource.
+   * @param key Key to modify
+   * @param op Operation to perform on 'key'
+   */
+  public async update<Type>(key: string, op: Operation<Type>) {
+    const nameChange = key === 'name';
+    const existingName = this.content.name;
+
+    await super.update(key, op);
+
+    const content = this.content as LinkType;
+    if (key === 'name') {
+      content.name = super.handleScalar(op) as string;
+    } else if (key === 'destinationCardTypes') {
+      content.destinationCardTypes = super.handleArray(
+        op,
+        key,
+        content.destinationCardTypes as Type[],
+      ) as string[];
+    } else if (key === 'enableLinkDescription') {
+      content.enableLinkDescription = super.handleScalar(op) as boolean;
+    } else if (key === 'inboundDisplayName') {
+      content.inboundDisplayName = super.handleScalar(op) as string;
+    } else if (key === 'outboundDisplayName') {
+      content.outboundDisplayName = super.handleScalar(op) as string;
+    } else if (key === 'sourceCardTypes') {
+      content.sourceCardTypes = super.handleArray(
+        op,
+        key,
+        content.sourceCardTypes as Type[],
+      ) as string[];
+    } else {
+      throw new Error(`Unknown property '${key}' for FieldType`);
+    }
+
+    await super.postUpdate(content, key, op);
+
+    // Renaming this card type causes that references to its name must be updated.
+    if (nameChange) {
+      await this.handleNameChange(existingName);
+    }
+  }
+
+  /**
+   * List where link type is used.
+   * Always returns card key references first, then calculation references.
+   *
+   * @param cards Optional. Check these cards for usage of this resource. If undefined, will check all cards.
+   * @returns array of card keys calculation filenames that refer this resource.
+   */
+  public async usage(cards?: Card[]): Promise<string[]> {
+    const resourceName = resourceNameToString(this.resourceName);
+    const allCards = cards || (await super.cards());
+
+    const cardsThatUseLinkType = allCards
+      .filter((card) =>
+        card.metadata?.links.find((item) => item.linkType === resourceName),
+      )
+      .filter(Boolean)
+      .map((card) => card.key);
+
+    const [cardContentReferences, calculations] = await Promise.all([
+      super.usage(allCards),
+      super.calculations(),
+    ]);
+
+    const cardReferences = [
+      ...cardsThatUseLinkType,
+      ...cardContentReferences,
+    ].sort(sortCards);
+
+    // Using Set to avoid duplicate cards
+    return [...new Set([...cardReferences, ...calculations])];
+  }
+
+  /**
+   * Validates the resource. If object is invalid, throws.
+   */
+  public async validate(content?: object) {
+    return super.validate(content);
+  }
+}